SSA UI kit

SSA UI kit is an open-source React-based library combining multiple UI Components, Widgets, Blocks, and Forms classified by application area and implemented following Atomic design principles.

SSA UI kit includes Figma design, integration with Firebase and examples of implementation for different business domains.

SSA UI kit was founded and is supported by SSA Group. The SSA UI kit source code is available under the MIT License.

We regularly post updates, new components, and improvements for the SSA UI kit on our blog: https://www.ssa.group/blog/ssa-ui-kit/ Please feel free to follow along.

🧠 Mental Model

SSA UI kit components are designed with the following principles:

• Composable & Flexible: Components use composition patterns and compound components for maximum flexibility
• Form-First: Form controls integrate seamlessly with React Hook Form for validation and state management
• Type-Safe: Full TypeScript support with comprehensive type definitions and JSDoc examples
• Accessible by Default: Components follow WAI-ARIA patterns and semantic HTML
• Themeable: Built on Emotion for CSS-in-JS styling with a centralized theme system
• Controlled & Uncontrolled: Components support both controlled and uncontrolled patterns

Component Patterns

Form Controls: Most form inputs integrate with React Hook Form. Use register prop for uncontrolled inputs, or value/onChange for controlled patterns.

Compound Components: Many components like Table, Modal, Field, and Dropdown use compound component patterns for flexible composition.

Status Props: Components use consistent prop naming like status (for validation states), disabled (for disabled state), and variant (for visual variants).

Controlled & Uncontrolled: Form controls follow the React convention — checked/defaultChecked for booleans, value/defaultValue for everything else.

Prop renames (v3.20). The library is converging on the names the DOM, MUI, Radix and Ant use. Each old prop still works and warns once per component in development; all are removed at the next major.

Old	New	Components
isDisabled	disabled	15 components
isChecked	checked	Radio
initialState	defaultChecked	Checkbox
externalState	checked	Checkbox
externalState, selectedItem	value	RadioGroup, ButtonGroup
selectedItems / defaultSelectedItems	value / defaultValue	Typeahead
color / defaultColor	value / defaultValue	ColorPicker
ariaLabel	aria-label	Breadcrumbs, Pagination
ariaLabelledby	aria-labelledby	CardContent, DropdownOptions, MultipleDropdownOptions, DropdownToggle
ariaControls	aria-controls	Accordion, Tab, LargeTab, DropdownToggle
opened / defaultOpened	open / defaultOpen	Drawer, useDrawer
opened / defaultOpened / onOpenedChange	open / defaultOpen / onOpenChange

🚀 Hero Example

Get started in 60 seconds. Here's a complete example showing Card, Button, Input, and Table working together:

import { ThemeProvider } from '@emotion/react';
import { FormProvider, useForm } from 'react-hook-form';
import {
  Card,
  CardHeader,
  CardContent,
  Button,
  Input,
  Typography,
  Table,
  TableHead,
  TableBody,
  TableRow,
  TableCell,
  TableCellHeader,
  mainTheme,
  Theme as T,
} from '@ssa-ui-kit/core';

// TypeScript: Extend Emotion theme types
declare module '@emotion/react' {
  export interface Theme extends T {}
}

function App() {
  const methods = useForm();
  const users = [
    { id: 1, name: 'John Doe', email: '[email protected]' },
    { id: 2, name: 'Jane Smith', email: '[email protected]' },
  ];

  return (
    <ThemeProvider theme={mainTheme}>
      <FormProvider {...methods}>
        <Card>
          <CardHeader>
            <Typography variant="h2">User Management</Typography>
          </CardHeader>
          <CardContent>
            <Input
              name="search"
              placeholder="Search users..."
              register={methods.register}
              css={{ marginBottom: 16 }}
            />
            <Table>
              <TableHead>
                <TableRow>
                  <TableCellHeader>Name</TableCellHeader>
                  <TableCellHeader>Email</TableCellHeader>
                  <TableCellHeader>Actions</TableCellHeader>
                </TableRow>
              </TableHead>
              <TableBody>
                {users.map((user) => (
                  <TableRow key={user.id}>
                    <TableCell>{user.name}</TableCell>
                    <TableCell>{user.email}</TableCell>
                    <TableCell>
                      <Button size="small" text="Edit" />
                    </TableCell>
                  </TableRow>
                ))}
              </TableBody>
            </Table>
          </CardContent>
        </Card>
      </FormProvider>
    </ThemeProvider>
  );
}

📦 Installation

# Core components
npm install @ssa-ui-kit/core
# or
yarn add @ssa-ui-kit/core
# or
pnpm add @ssa-ui-kit/core

# Hooks (optional, separate package)
npm install @ssa-ui-kit/hooks
# or
yarn add @ssa-ui-kit/hooks
# or
pnpm add @ssa-ui-kit/hooks

⚠️ Vite Users: See the Vite Configuration section below for required setup to avoid useFormContext() errors.

Peer Dependencies

Make sure you have React 19 or later, Emotion, and React Hook Form installed:

npm install react@^19 react-dom@^19 @emotion/react @emotion/styled react-hook-form

Note: The UI kit requires React 19 or later (>=19). React 18 is not supported — some components rely on React 19 features such as refs-as-props.

Vite + React Hook Form

As of the dual ESM/CJS build, the react-hook-form alias below should no longer be needed. @ssa-ui-kit/core, @ssa-ui-kit/hooks, @ssa-ui-kit/utils and @ssa-ui-kit/widgets now ship a real ESM bundle (dist/index.mjs) alongside the CommonJS one, and their exports map points import at it. The ESM bundle emits import ... from 'react-hook-form' rather than require('react-hook-form'), so Vite resolves a single shared instance.

The original problem

The UI kit was previously published as a CommonJS-only bundle. When webpack externalised react-hook-form it emitted require('react-hook-form'), while Vite loaded the ESM build (index.esm.mjs) for the app. Two module instances meant two React contexts, so FormProvider wrote into one and useFormContext() read from the other — returning null inside UI kit components.

If you still hit useFormContext() returned null

First check you are resolving the ESM entry (node_modules/@ssa-ui-kit/core/dist/index.mjs). If you are, the most likely cause is now duplicate copies of react-hook-form in your dependency tree rather than a module-format mismatch. This is common when the kit is consumed via npm link, file: or a workspace symlink, because the linked package resolves its own peer dependencies from its tree instead of yours. resolve.dedupe is the fix for that case:

export default defineConfig({
  resolve: { dedupe: ['react', 'react-dom', 'react-hook-form'] },
});

Duplicate copies of the kit itself

Shipping both bundles introduces one trade-off worth knowing about. exports.import resolves to dist/index.mjs and exports.require to dist/index.js, so a dependency graph that reaches @ssa-ui-kit/core both ways loads both files — and each gets its own module scope. React contexts are per-instance, so the kit's own contexts then exist twice: a ThemeProvider from one copy is invisible to a useTheme from the other, a PopoverTrigger cannot find the Popover wrapping it, and so on. Most apps are wholly ESM or wholly CJS and never hit this; the usual trigger is npm link, a file: dependency, or a workspace symlink giving the linked package its own node_modules.

The kit detects this and warns once in development:

[ssa-ui-kit] Two copies of `@ssa-ui-kit/core` are loaded in this runtime.

Deduplicate the same way as above:

export default defineConfig({
  resolve: { dedupe: ['@ssa-ui-kit/core', 'react', 'react-dom', 'react-hook-form'] },
});

Element type is invalid ... but got: object under vite dev

Fixed. If you are on 3.20.1 or earlier, the symptom is a chart or colour-picker component that renders fine after vite build but throws under vite dev — often as a 404 and a reload loop, and only once the component actually mounts:

Element type is invalid: expected a string (for built-in components) or a
class/function (for composite components) but got: object.

The ESM bundle externalised two CommonJS-only packages (react-plotly.js, @rc-component/color-picker) and imported them as import { default as X } from '…'. A plain ESM loader binds default to the whole module.exports of a CommonJS module — __esModule is a bundler convention, not part of the interop spec — so X arrived as { __esModule: true, default: Component }. Rollup rewrites those dependencies during vite build, which is why only vite dev was affected, and only for deps Vite chose not to pre-bundle.

Both are now bundled into the kit, so no consumer configuration is needed. On an older version, the workaround is to force Vite to pre-bundle them:

export default defineConfig({
  optimizeDeps: {
    exclude: ['@ssa-ui-kit/core'],
    include: ['react-plotly.js', '@rc-component/color-picker'],
  },
});

Add this alias to your vite.config.ts:

import path from 'node:path';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  resolve: {
    dedupe: ['react', 'react-dom', 'react-hook-form'],
    alias: {
      '@': path.resolve(__dirname, './src'),
      // ⚠️ CRITICAL: Force CommonJS bundle for react-hook-form
      // This ensures the UI kit (expecting CommonJS) uses the same instance as your app
      'react-hook-form': path.resolve(
        __dirname,
        './node_modules/react-hook-form/dist/index.cjs.js' // ← CommonJS bundle
      ),
    },
  },
  optimizeDeps: {
    include: ['react-hook-form'],
  },
});

React contexts are instance-specific. Even with the same package version, if the library uses a different module instance (ESM vs CJS), the context won't be shared. Forcing the CommonJS bundle made both your app and the CJS-only UI kit use the same instance.

Related Issue: react-hook-form#8281

💡 Note: This only ever applied to Vite projects. Webpack projects did not need it.

🏁 Quick Start

1. Set up Theme Provider

Wrap your app with ThemeProvider from @emotion/react and pass mainTheme:

import { ThemeProvider } from '@emotion/react';
import { mainTheme, Theme as T } from '@ssa-ui-kit/core';

// TypeScript: Extend Emotion theme types (required for TypeScript projects)
declare module '@emotion/react' {
  export interface Theme extends T {}
}

function App() {
  return (
    <ThemeProvider theme={mainTheme}>
      {/* Your app components */}
    </ThemeProvider>
  );
}

2. TypeScript Setup (if using TypeScript)

In your main entry file (e.g., src/index.tsx), add the theme type augmentation:

import '@emotion/react';
import { Theme as T } from '@ssa-ui-kit/core';

declare module '@emotion/react' {
  export interface Theme extends T {}
}

[!TIP] If you are using a monorepo or a custom Vite/Webpack setup, we recommend putting the declare module '@emotion/react' block in a global types/emotion.d.ts file to keep your components clean.

📚 Component Examples

Button

Buttons come in multiple variants, sizes, and can include icons:

import { Button, Icon } from '@ssa-ui-kit/core';

// Basic button
<Button text="Click me" variant="primary" size="medium" />

// Button with icon
<Button
  text="Save"
  startIcon={<Icon name="check" size={16} />}
  variant="secondary"
/>

// Variants: primary, secondary, tertiary, info, attention
// Sizes: small, medium, large

Input

Form inputs with validation states and helper text:

import { Input } from '@ssa-ui-kit/core';
import { useForm, FormProvider } from 'react-hook-form';

function MyForm() {
  const methods = useForm();
  
  return (
    <FormProvider {...methods}>
      <Input
        name="email"
        placeholder="Enter your email"
        status="basic" // or 'error', 'success'
        helperText="We'll never share your email"
        showHelperText
      />
    </FormProvider>
  );
}

Note: Input components work with react-hook-form. Wrap your form with FormProvider from react-hook-form.

Table

Build data tables with sorting, styling, and row actions:

import {
  Table,
  TableHead,
  TableBody,
  TableRow,
  TableCell,
  TableCellHeader,
} from '@ssa-ui-kit/core';

function UserTable() {
  const data = [
    { id: 1, name: 'John Doe', email: '[email protected]', role: 'Admin' },
    { id: 2, name: 'Jane Smith', email: '[email protected]', role: 'User' },
  ];

  return (
    <Table>
      <TableHead>
        <TableRow>
          <TableCellHeader>Name</TableCellHeader>
          <TableCellHeader>Email</TableCellHeader>
          <TableCellHeader>Role</TableCellHeader>
        </TableRow>
      </TableHead>
      <TableBody>
        {data.map((user) => (
          <TableRow key={user.id}>
            <TableCell>{user.name}</TableCell>
            <TableCell>{user.email}</TableCell>
            <TableCell>{user.role}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  );
}

🎣 Hooks Examples

useApi

Handle async data fetching with loading and error states:

import { useApi } from '@ssa-ui-kit/hooks';

function UserList() {
  const { data, isLoading, error, query } = useApi(
    async (userId: string) => {
      const response = await fetch(`/api/users/${userId}`);
      return response.json();
    }
  );

  useEffect(() => {
    query('123');
  }, []);

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  return <div>{data.name}</div>;
}

useToggle

Toggle between multiple values (useful for boolean or multi-state toggles):

import { useToggle } from '@ssa-ui-kit/hooks';

function ToggleExample() {
  // Boolean toggle (default)
  const [isOpen, toggleOpen] = useToggle();

  // Multi-state toggle
  const [theme, toggleTheme] = useToggle(['light', 'dark', 'auto']);

  return (
    <div>
      <button onClick={() => toggleOpen()}>
        {isOpen ? 'Close' : 'Open'}
      </button>
      <button onClick={() => toggleTheme()}>
        Theme: {theme}
      </button>
    </div>
  );
}

useWindowSize

Track window dimensions with reactive updates:

import { useWindowSize } from '@ssa-ui-kit/hooks';

function ResponsiveComponent() {
  const { width, height } = useWindowSize();
  const isMobile = width < 768;

  return (
    <div>
      <p>Window size: {width}x{height}</p>
      {isMobile ? <MobileView /> : <DesktopView />}
    </div>
  );
}

Other Available Hooks

• useClickOutside - Detect clicks outside an element
• useDebouncedCallback - Debounce function calls
• useThrottledCallback - Throttle function calls
• useClipboard - Copy to clipboard functionality
• useDeviceType - Detect device type
• useResizeObserver - Observe element size changes
• usePaginationRange - Generate pagination ranges

🛠️ Core Technologies

The project is built using:

• React 19+
• TypeScript
• CSS-in-JS with Emotion
• Charts with Nivo
• Floating UI for tooltips
• Storybook for component documentation
• pNPM as package manager

📖 Documentation

For detailed component documentation, examples, and API references, visit our Storybook documentation.

🤖 Using the kit with a coding agent

Every published package ships an AI source map — a single-file index of its public API, generated from the TypeScript program so it can never drift from the real exports:

node_modules/@ssa-ui-kit/core/dist/ai/source-map.md
node_modules/@ssa-ui-kit/utils/dist/ai/source-map.md
node_modules/@ssa-ui-kit/hooks/dist/ai/source-map.md
node_modules/@ssa-ui-kit/widgets/dist/ai/source-map.md
node_modules/@ssa-ui-kit/templates/dist/ai/source-map.md
node_modules/@ssa-ui-kit/infra-dash/dist/ai/source-map.md

It lists every component grouped by area, each one's library-specific props with their literal unions and defaults, plus the hooks, contexts and exported types. The alternative is grepping ~940 .d.ts files, so pointing your agent at this file first is considerably cheaper.

Agents can read node_modules, but their search tools skip it by default, so they won't find the map unless told where it is. Add one line to your project's CLAUDE.md (Claude Code) or AGENTS.md (Codex):

When using @ssa-ui-kit, read node_modules/@ssa-ui-kit/<package>/dist/ai/source-map.md
for each @ssa-ui-kit package the app depends on (core, utils, hooks, widgets,
templates, infra-dash) for the component and prop index before writing UI code.

Start from the Component roster near the top to see what exists, then search the file for #### <ComponentName> to get that component's props. For full prop documentation and usage examples, read the matching .d.ts under the package's dist/ folder (e.g. dist/components/<ComponentName>/ in core).

🤝 Want to contribute?

Please refer to our CONTRIBUTING.md.

📄 License

MIT

🙏 Thanks

Thanks to Lost Pixel for providing the visual testing platform that helps us review UI changes and catch visual regressions.