Component Library

A comprehensive collection of reusable UI components built with React, TypeScript, and our design system tokens.

Overview

The SUDIGITAL component library provides a complete set of accessible, performant, and customizable components for building modern web applications. Each component follows our design principles and includes multiple variants, states, and sizes.

Component Categories

Basic Components

Button

The Button component is used for actions in forms, dialogs, and more.

import { Button } from '@sudigital/design-system';

// Basic usage
<Button>Click me</Button>

// With variants
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>

// With sizes
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

// With states
<Button loading>Loading...</Button>
<Button disabled>Disabled</Button>

// With icons
<Button leftIcon={<PlusIcon />}>Add Item</Button>
<Button rightIcon={<ArrowRightIcon />}>Continue</Button>

Props:

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  disabled?: boolean
  loading?: boolean
  leftIcon?: React.ReactNode
  rightIcon?: React.ReactNode
  children: React.ReactNode
  onClick?: () => void
}

Input

Text input component with validation and various configurations.

import { Input } from '@sudigital/design-system';

// Basic usage
<Input placeholder="Enter your name" />

// With label and help text
<Input
  label="Email Address"
  placeholder="john@example.com"
  helperText="We'll never share your email"
/>

// With validation
<Input
  label="Password"
  type="password"
  error="Password must be at least 8 characters"
  required
/>

// Different sizes
<Input size="sm" placeholder="Small input" />
<Input size="md" placeholder="Medium input" />
<Input size="lg" placeholder="Large input" />

// With icons
<Input
  leftIcon={<SearchIcon />}
  placeholder="Search..."
/>

Props:

interface InputProps {
  type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url'
  size?: 'sm' | 'md' | 'lg'
  label?: string
  placeholder?: string
  helperText?: string
  error?: string
  required?: boolean
  disabled?: boolean
  leftIcon?: React.ReactNode
  rightIcon?: React.ReactNode
  value?: string
  onChange?: (value: string) => void
}

Select

Dropdown component for selecting from a list of options.

import { Select } from '@sudigital/design-system';

const options = [
  { value: 'us', label: 'United States' },
  { value: 'ca', label: 'Canada' },
  { value: 'uk', label: 'United Kingdom' },
];

// Basic usage
<Select
  options={options}
  placeholder="Select a country"
/>

// With multiple selection
<Select
  options={options}
  multiple
  placeholder="Select countries"
/>

// With search
<Select
  options={options}
  searchable
  placeholder="Search and select"
/>

Checkbox

Checkbox component for binary choices.

import { Checkbox } from '@sudigital/design-system';

// Basic usage
<Checkbox>Accept terms and conditions</Checkbox>

// With description
<Checkbox
  label="Email notifications"
  description="Get notified about important updates"
/>

// Checkbox group
<CheckboxGroup label="Select your interests">
  <Checkbox value="tech">Technology</Checkbox>
  <Checkbox value="design">Design</Checkbox>
  <Checkbox value="business">Business</Checkbox>
</CheckboxGroup>

Radio

Radio button component for single selection from multiple options.

import { Radio, RadioGroup } from '@sudigital/design-system';

// Radio group
<RadioGroup label="Select a plan" name="plan">
  <Radio value="free">Free Plan</Radio>
  <Radio value="pro">Pro Plan</Radio>
  <Radio value="enterprise">Enterprise Plan</Radio>
</RadioGroup>

// With descriptions
<RadioGroup label="Choose your subscription">
  <Radio
    value="monthly"
    label="Monthly"
    description="$29/month, cancel anytime"
  />
  <Radio
    value="yearly"
    label="Yearly"
    description="$290/year, 2 months free"
  />
</RadioGroup>

Layout Components

Card

Container component for grouping related content.

import { Card } from '@sudigital/design-system';

// Basic card
<Card>
  <h3>Card Title</h3>
  <p>Card content goes here.</p>
</Card>

// With header and footer
<Card>
  <Card.Header>
    <h3>User Profile</h3>
  </Card.Header>
  <Card.Body>
    <p>User information and settings.</p>
  </Card.Body>
  <Card.Footer>
    <Button>Save Changes</Button>
  </Card.Footer>
</Card>

// Different variants
<Card variant="elevated">Elevated card</Card>
<Card variant="outlined">Outlined card</Card>
<Card variant="filled">Filled card</Card>

Stack

Component for stacking elements with consistent spacing.

import { Stack } from '@sudigital/design-system';

// Vertical stack
<Stack direction="vertical" spacing="md">
  <Button>First Button</Button>
  <Button>Second Button</Button>
  <Button>Third Button</Button>
</Stack>

// Horizontal stack
<Stack direction="horizontal" spacing="sm">
  <Button>Cancel</Button>
  <Button variant="primary">Save</Button>
</Stack>

// With alignment
<Stack
  direction="horizontal"
  spacing="md"
  align="center"
  justify="space-between"
>
  <Text>Total: $99.99</Text>
  <Button>Checkout</Button>
</Stack>

Grid

Responsive grid component for layout.

import { Grid } from '@sudigital/design-system';

// Basic grid
<Grid cols={3} gap="md">
  <Card>Item 1</Card>
  <Card>Item 2</Card>
  <Card>Item 3</Card>
</Grid>

// Responsive grid
<Grid
  cols={{ xs: 1, sm: 2, md: 3, lg: 4 }}
  gap="lg"
>
  {items.map(item => (
    <Card key={item.id}>{item.content}</Card>
  ))}
</Grid>

Feedback Components

Alert

Component for displaying important messages to users.

import { Alert } from '@sudigital/design-system';

// Different variants
<Alert variant="info">
  This is an informational message.
</Alert>

<Alert variant="success">
  Your changes have been saved successfully.
</Alert>

<Alert variant="warning">
  Please review your information before proceeding.
</Alert>

<Alert variant="error">
  An error occurred while processing your request.
</Alert>

// With title and dismissible
<Alert
  variant="info"
  title="New Feature Available"
  dismissible
  onDismiss={() => console.log('Alert dismissed')}
>
  Check out our new dashboard features in the settings panel.
</Alert>

Toast

Notification component for temporary messages.

import { toast } from '@sudigital/design-system'

// Show toast notifications
toast.success('Operation completed successfully!')
toast.error('Something went wrong. Please try again.')
toast.warning('Your session will expire in 5 minutes.')
toast.info('New updates are available.')

// Custom toast with action
toast.custom({
  title: 'Update Available',
  message: 'A new version is ready to install.',
  action: {
    label: 'Update Now',
    onClick: () => console.log('Updating...'),
  },
  duration: 10000,
})

Loading

Loading states and skeleton components.

import { Loading, Skeleton } from '@sudigital/design-system';

// Loading spinner
<Loading size="sm" />
<Loading size="md" />
<Loading size="lg" />

// Loading overlay
<Loading overlay>
  <div>Content that will be overlayed</div>
</Loading>

// Skeleton placeholders
<Skeleton height="20px" width="200px" />
<Skeleton.Text lines={3} />
<Skeleton.Circle size="40px" />
<Skeleton.Rectangle width="300px" height="200px" />

Navigation Components

Breadcrumb

Navigation component showing the current page's location.

import { Breadcrumb } from '@sudigital/design-system';

const breadcrumbItems = [
  { label: 'Home', href: '/' },
  { label: 'Products', href: '/products' },
  { label: 'Laptops', href: '/products/laptops' },
  { label: 'MacBook Pro' }
];

<Breadcrumb items={breadcrumbItems} />

// With custom separator
<Breadcrumb
  items={breadcrumbItems}
  separator=">"
/>

Tabs

Tab component for organizing content into sections.

import { Tabs } from '@sudigital/design-system';

<Tabs defaultValue="overview">
  <Tabs.List>
    <Tabs.Tab value="overview">Overview</Tabs.Tab>
    <Tabs.Tab value="details">Details</Tabs.Tab>
    <Tabs.Tab value="reviews">Reviews</Tabs.Tab>
  </Tabs.List>

  <Tabs.Panel value="overview">
    <p>Overview content...</p>
  </Tabs.Panel>

  <Tabs.Panel value="details">
    <p>Detailed information...</p>
  </Tabs.Panel>

  <Tabs.Panel value="reviews">
    <p>Customer reviews...</p>
  </Tabs.Panel>
</Tabs>

Pagination

Component for navigating through pages of content.

import { Pagination } from '@sudigital/design-system';

<Pagination
  current={3}
  total={50}
  pageSize={10}
  showSizeChanger
  showQuickJumper
  onChange={(page, pageSize) => {
    console.log('Page changed:', page, pageSize);
  }}
/>

Data Display Components

Table

Component for displaying tabular data.

import { Table } from '@sudigital/design-system';

const columns = [
  {
    header: 'Name',
    accessor: 'name',
    sortable: true
  },
  {
    header: 'Email',
    accessor: 'email'
  },
  {
    header: 'Role',
    accessor: 'role',
    render: (value) => <Badge variant={value}>{value}</Badge>
  },
  {
    header: 'Actions',
    render: (row) => (
      <Stack direction="horizontal" spacing="sm">
        <Button size="sm" variant="outline">Edit</Button>
        <Button size="sm" variant="outline">Delete</Button>
      </Stack>
    )
  }
];

const data = [
  { id: 1, name: 'John Doe', email: 'john@example.com', role: 'admin' },
  { id: 2, name: 'Jane Smith', email: 'jane@example.com', role: 'user' }
];

<Table
  columns={columns}
  data={data}
  sortable
  pagination
  selection
  onSort={(column, direction) => {
    console.log('Sort:', column, direction);
  }}
  onSelectionChange={(selectedRows) => {
    console.log('Selected:', selectedRows);
  }}
/>

Badge

Small component for displaying status or labels.

import { Badge } from '@sudigital/design-system';

// Different variants
<Badge variant="default">Default</Badge>
<Badge variant="primary">Primary</Badge>
<Badge variant="success">Success</Badge>
<Badge variant="warning">Warning</Badge>
<Badge variant="error">Error</Badge>

// Different sizes
<Badge size="sm">Small</Badge>
<Badge size="md">Medium</Badge>
<Badge size="lg">Large</Badge>

// With icon
<Badge variant="success" leftIcon={<CheckIcon />}>
  Completed
</Badge>

Avatar

Component for displaying user profile pictures.

import { Avatar } from '@sudigital/design-system';

// With image
<Avatar
  src="https://example.com/avatar.jpg"
  alt="John Doe"
  size="md"
/>

// With initials fallback
<Avatar
  name="John Doe"
  size="lg"
/>

// Avatar group
<AvatarGroup max={3}>
  <Avatar src="user1.jpg" name="User 1" />
  <Avatar src="user2.jpg" name="User 2" />
  <Avatar src="user3.jpg" name="User 3" />
  <Avatar src="user4.jpg" name="User 4" />
  <Avatar src="user5.jpg" name="User 5" />
</AvatarGroup>

Overlay Components

Modal

Modal dialog component for focused interactions.

import { Modal } from '@sudigital/design-system';

const [isOpen, setIsOpen] = useState(false);

<Modal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="Confirm Action"
  size="md"
>
  <Modal.Body>
    <p>Are you sure you want to delete this item?</p>
  </Modal.Body>

  <Modal.Footer>
    <Button
      variant="outline"
      onClick={() => setIsOpen(false)}
    >
      Cancel
    </Button>
    <Button
      variant="primary"
      onClick={() => {
        // Handle delete
        setIsOpen(false);
      }}
    >
      Delete
    </Button>
  </Modal.Footer>
</Modal>

Tooltip

Component for displaying additional information on hover.

import { Tooltip } from '@sudigital/design-system';

<Tooltip content="This is a helpful tooltip">
  <Button>Hover me</Button>
</Tooltip>

// With different placements
<Tooltip content="Top placement" placement="top">
  <Button>Top</Button>
</Tooltip>

<Tooltip content="Right placement" placement="right">
  <Button>Right</Button>
</Tooltip>

// With rich content
<Tooltip
  content={
    <div>
      <strong>Advanced Settings</strong>
      <p>Configure advanced options for your account.</p>
    </div>
  }
>
  <Button>Advanced</Button>
</Tooltip>

Popover

Component for displaying content in a floating container.

import { Popover } from '@sudigital/design-system';

<Popover
  trigger={<Button>Open Popover</Button>}
  content={
    <div style={{ padding: '16px', maxWidth: '200px' }}>
      <h4>Popover Title</h4>
      <p>This is the popover content.</p>
      <Button size="sm">Action</Button>
    </div>
  }
  placement="bottom"
/>

Form Components

Form

Complete form component with validation.

import { Form, FormField } from '@sudigital/design-system';
import { z } from 'zod';

const schema = z.object({
  name: z.string().min(1, 'Name is required'),
  email: z.string().email('Invalid email address'),
  age: z.number().min(18, 'Must be 18 or older')
});

<Form
  schema={schema}
  onSubmit={(data) => console.log('Form data:', data)}
>
  <FormField name="name">
    <Input label="Full Name" />
  </FormField>

  <FormField name="email">
    <Input label="Email Address" type="email" />
  </FormField>

  <FormField name="age">
    <Input label="Age" type="number" />
  </FormField>

  <Button type="submit">Submit</Button>
</Form>

Styling and Customization

CSS Variables

All components use CSS custom properties for easy customization:

.my-custom-button {
  --button-primary-bg: #your-brand-color;
  --button-primary-hover-bg: #your-brand-color-dark;
  --button-border-radius: 8px;
}

Theme Customization

import { ThemeProvider } from '@sudigital/design-system';

const customTheme = {
  colors: {
    primary: {
      50: '#f0f9ff',
      500: '#0ea5e9',
      600: '#0284c7'
    }
  },
  spacing: {
    sm: '8px',
    md: '16px',
    lg: '24px'
  }
};

<ThemeProvider theme={customTheme}>
  <App />
</ThemeProvider>

Component Variants

Create custom variants using the variant system:

// Custom button variant
const CustomButton = styled(Button)`
  &.btn--custom {
    background: linear-gradient(45deg, #fe6b8b 30%, #ff8e53 90%);
    color: white;
  }
`;

<CustomButton variant="custom">
  Gradient Button
</CustomButton>

Accessibility Features

All components include comprehensive accessibility features:

• Keyboard Navigation: Full keyboard support with logical tab order
• Screen Reader Support: Proper ARIA labels and semantic HTML
• Focus Management: Visible focus indicators and focus trapping
• Color Contrast: WCAG 2.1 AA compliant color combinations
• Reduced Motion: Respects user's motion preferences

Best Practices

Component Usage

1. Use Semantic HTML: Always use the most appropriate HTML element
2. Provide Labels: Include proper labels for form elements
3. Handle Loading States: Show loading indicators for async operations
4. Error Handling: Display clear error messages and recovery options
5. Responsive Design: Test components across different screen sizes

Performance

1. Tree Shaking: Import only the components you need
2. Lazy Loading: Use React.lazy for large components
3. Memoization: Use React.memo for expensive re-renders
4. Virtualization: Use virtual lists for large datasets

Testing

import { render, screen, fireEvent } from '@testing-library/react';
import { Button } from '@sudigital/design-system';

test('Button handles click events', () => {
  const handleClick = jest.fn();
  render(<Button onClick={handleClick}>Click me</Button>);

  fireEvent.click(screen.getByRole('button'));
  expect(handleClick).toHaveBeenCalledTimes(1);
});

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Related Resources

• Design Tokens - Design system foundation
• Pattern Library - Common UI patterns
• Storybook - Interactive component explorer
• GitHub - Source code and issues