https://github.com/ssagroup/ui-kit
SSA UI kit is an open-source React library offering AI-friendly components to streamline the creation of dashboards and admin panels.
https://github.com/ssagroup/ui-kit
atomic-design charts dashboard-templates emotion form-builder react typescript ui-components ui-kit
Last synced: 3 months ago
JSON representation
SSA UI kit is an open-source React library offering AI-friendly components to streamline the creation of dashboards and admin panels.
- Host: GitHub
- URL: https://github.com/ssagroup/ui-kit
- Owner: ssagroup
- License: mit
- Created: 2023-06-01T12:56:49.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-10-08T20:26:53.000Z (8 months ago)
- Last Synced: 2025-10-09T12:16:36.366Z (8 months ago)
- Topics: atomic-design, charts, dashboard-templates, emotion, form-builder, react, typescript, ui-components, ui-kit
- Language: TypeScript
- Homepage: https://www.ssa.group/ssa-ui-kit/
- Size: 4.83 MB
- Stars: 8
- Watchers: 3
- Forks: 1
- Open Issues: 47
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
SSA UI kit
[](https://github.com/ssagroup/ui-kit/blob/main/CODE_OF_CONDUCT.md)
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), `isDisabled` (for disabled state), and `variant` (for visual variants).
## 🚀 Hero Example
Get started in 60 seconds. Here's a complete example showing Card, Button, Input, and Table working together:
```tsx
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: 'john@example.com' },
{ id: 2, name: 'Jane Smith', email: 'jane@example.com' },
];
return (
User Management
Name
Email
Actions
{users.map((user) => (
{user.name}
{user.email}
))}
);
}
```
## 📦 Installation
```bash
# 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](#-critical-vite-configuration-for-react-hook-form) section below for required setup to avoid `useFormContext()` errors.
### Peer Dependencies
Make sure you have React 19.x, Emotion, and React Hook Form installed:
```bash
npm install react@19.x react-dom@19.x @emotion/react @emotion/styled react-hook-form
```
## ⚠️ CRITICAL: Vite Configuration for React Hook Form
> **🚨 IMPORTANT**: If you're using **Vite** and experiencing `useFormContext() returned null` errors with form components (like `DateRangePicker`, `DatePicker`, etc.), you **MUST** configure Vite to use the CommonJS bundle of `react-hook-form`.
### The Problem
The UI kit (`@ssa-ui-kit/core`) is built with webpack and uses CommonJS externals. When webpack externalizes `react-hook-form`, it expects the **CommonJS version**. However, Vite defaults to the **ESM bundle** (`index.esm.mjs`). Different module instances = different React contexts, causing `useFormContext()` to return `null` inside UI kit components.
### The Fix
Add this alias to your `vite.config.ts`:
```typescript
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'],
},
});
```
### Why This Matters
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. Using the CommonJS bundle ensures both your app and the webpack-built UI kit use the **same instance**.
**Related Issue**: [react-hook-form#8281](https://github.com/react-hook-form/react-hook-form/issues/8281)
> **💡 Note**: This only applies to Vite projects. Webpack projects don't need this configuration.
## 🏁 Quick Start
### 1. Set up Theme Provider
Wrap your app with `ThemeProvider` from `@emotion/react` and pass `mainTheme`:
```tsx
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 (
{/* Your app components */}
);
}
```
### 2. TypeScript Setup (if using TypeScript)
In your main entry file (e.g., `src/index.tsx`), add the theme type augmentation:
```tsx
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:
```tsx
import { Button, Icon } from '@ssa-ui-kit/core';
// Basic button
// Button with icon
}
variant="secondary"
/>
// Variants: primary, secondary, tertiary, info, attention
// Sizes: small, medium, large
```
### Input
Form inputs with validation states and helper text:
```tsx
import { Input } from '@ssa-ui-kit/core';
import { useForm, FormProvider } from 'react-hook-form';
function MyForm() {
const methods = useForm();
return (
);
}
```
**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:
```tsx
import {
Table,
TableHead,
TableBody,
TableRow,
TableCell,
TableCellHeader,
} from '@ssa-ui-kit/core';
function UserTable() {
const data = [
{ id: 1, name: 'John Doe', email: 'john@example.com', role: 'Admin' },
{ id: 2, name: 'Jane Smith', email: 'jane@example.com', role: 'User' },
];
return (
Name
Email
Role
{data.map((user) => (
{user.name}
{user.email}
{user.role}
))}
);
}
```
## 🎣 Hooks Examples
### useApi
Handle async data fetching with loading and error states:
```tsx
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
Loading...;
if (error) return Error: {error.message};
return {data.name};
}
```
### useToggle
Toggle between multiple values (useful for boolean or multi-state toggles):
```tsx
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 (
toggleOpen()}>
{isOpen ? 'Close' : 'Open'}
toggleTheme()}>
Theme: {theme}
);
}
```
### useWindowSize
Track window dimensions with reactive updates:
```tsx
import { useWindowSize } from '@ssa-ui-kit/hooks';
function ResponsiveComponent() {
const { width, height } = useWindowSize();
const isMobile = width < 768;
return (
Window size: {width}x{height}
{isMobile ? : }
);
}
```
### 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](https://react.dev/) 19.x
- [TypeScript](https://www.typescriptlang.org/)
- CSS-in-JS with [Emotion](https://emotion.sh/docs/introduction)
- Charts with [Nivo](https://nivo.rocks/)
- [Floating UI](https://floating-ui.com/) for tooltips
- [Storybook](https://storybook.js.org/) for component documentation
- [pNPM](https://pnpm.io/) as package manager
## 📖 Documentation
For detailed component documentation, examples, and API references, visit our [Storybook documentation](https://ssagroup.github.io/ui-kit/).
## 🤝 Want to contribute?
Please refer to our [CONTRIBUTING.md](https://github.com/ssagroup/ui-kit/blob/main/CONTRIBUTING.md).
## 📄 License
[MIT](https://github.com/ssagroup/ui-kit/blob/main/LICENSE)
## 🙏 Thanks
Thanks to [Lost Pixel](https://www.lost-pixel.com/) for providing the visual testing platform that helps us review UI changes and catch visual regressions.