npm package: @profiq/ui
Description: A React UI component library built on ShadCN specially for internal use by profiq
Latest version: 0.2.1

# @profiq/ui

A React UI component library built on [ShadCN](https://ui.shadcn.com/) and [Radix UI](https://www.radix-ui.com/), designed for internal use by Profiq.

## Documentation

**View the complete component library and documentation in [storybook](https://ui-react.profiq.com)**

## Features

- **Themes** - Components built around Profiq and ShadCN themes in light/dark variants
- **TypeScript** - Full TypeScript support with comprehensive type definitions
- **Customizable** - Tailwind CSS-based styling with CSS variables

## Requirements

- React 18.0.0+ or React 19.0.0+
- Tailwind CSS 4.0.0+
- Node.js 18+

## Installation

Install the package via npm:

```
npm install @profiq/ui
```

## Setup

### 1. Import Styles

Import the library styles in your application's entry point:

```tsx
// eg. src/main.tsx, src/index.tsx
import "@profiq/ui/index.css";
import "./index.css"; // Your app's index.css
```

**Important:** Import `@profiq/ui/index.css` before your application's CSS to allow proper style overrides.

### 2. Configure Themes

Import and apply themes to your application. Themes are applied via CSS classes on a parent element (typically `<html>` or a wrapper `<div>`):

```tsx
// src/App.tsx
import { themes, type Theme } from "@profiq/ui";
import { useState } from "react";

function App() {
  const [currentTheme, setCurrentTheme] = useState<Theme>("profiq");

  return (
    <div className={currentTheme}>
      {/* Your app content */}
      <YourComponents />
    </div>
  );
}
```

**Available themes:**

- `profiq` / `profiq-dark` - Profiq brand theme
- `shadcn` / `shadcn-dark` - ShadCN default theme
- `green` / `green-dark` - ShadCN green theme
- `red` / `red-dark` - ShadCN red theme

### 3. Configure Tailwind CSS

Configure Tailwind to scan the library's components for class names.

Place this line into your index.css (where you import tailwind)

```
@source "../node_modules/@profiq/ui/dist";
```

## Usage

Import and use components in your application:

```tsx
import { Button } from "@profiq/ui";

function MyComponent() {
  return (
    <Button
      variant="default"
      size="default"
      onClick={() => console.log("Clicked!")}
    >
      Click me
    </Button>
  );
}
```

### Controlled Components

Creating a controlled component is as simple as providing a value and an onChange handler:

```tsx
import { Pagination } from "@profiq/ui";

function MyPaginatedList() {
  const [page, setPage] = useState(1);

  return (
    <Pagination totalPages={10} currentPage={page} onPageChange={setPage} />
  );
}
```

See the documentation on [storybook](https://ui-react.profiq.com)

### Applying Themes to Components

The theme is applied by adding a CSS class to a parent element.
However individual components can override their parent theme by providing a `theme` prop like this:

```tsx
import { Button } from "@profiq/ui";

function ThemedButtons() {
  return (
    <div>
      <Button theme="profiq">Profiq Theme</Button>
      <Button theme="shadcn">ShadCN Theme</Button>
    </div>
  );
}
```

## Available Components

The library currently includes these components:

### General

- **Button | ButtonGroup** - Versatile button with multiple variants and sizes
- **Toggle | ToggleGroup** - Toggle button component
- **Avatar** - User avatar component
- **Text** - Typography component with variants

### Form Components

- **Input** - Text input with validation states
- **Select** - Dropdown select component
- **Switch** - Toggle switch component
- **Checkbox** - Checkbox input
- **Textarea** - Multi-line text input
- **Date Picker** - Date selection component
- **Slider** - Range slider component

### Layout Components

- **Accordion** - Collapsible content group
- **Table** - Data table with sorting and pagination

### Navigation Components

- **Pagination** - Page navigation controls
- **Breadcrumb** - Breadcrumb navigation
- **Dropdown Menu** - Contextual menu component

### Overlay

- **Badge** - Status and label badges
- **Tooltip** - Hover tooltips

### Display Components

Visit [our Storybook](https://ui-react.profiq.com) for complete documentation and live examples of all components.

## TypeScript Support

The library is written in TypeScript and provides full type definitions. All components export their prop types:

```tsx
import { Button, type ButtonProps } from "@profiq/ui";
import type { Theme } from "@profiq/ui";

const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};
```

## Customizing Themes

Themes are defined using CSS variables. You can customize them by overriding the CSS variables in your own stylesheet:

```css
/* src/index.css */
.profiq {
  --primary: #8ec549;
  --primary-foreground: #002c62;
  --background: #ffffff;
  --foreground: #002c62;
  /* ... other variables */
}
```

## Contributing

This library is maintained by Profiq for internal use.
For bug reports or feature requests, please open an issue on [GitLab](https://gitlab.com/profiq/all/infra/profiq-ui/-/issues).

## 🔗 Links

- [Storybook Documentation](https://ui-react.profiq.com)
- [GitLab Repository](https://gitlab.com/profiq/all/infra/profiq-ui)
- [Issue Tracker](https://gitlab.com/profiq/all/infra/profiq-ui/-/issues)

---