---
description: UI Components API reference and guidelines
globs: **/*.tsx
alwaysApply: false
---

# UI Components

- Reusable UI components are defined in the "packages/ui" package named "@kit/ui".
- By exporting the component from the "exports" field, we can import it using the "@kit/ui/{component-name}" format.

## Styling

- Styling is done using Tailwind CSS. We use the "cn" function from the "@kit/ui/utils" package to generate class names.
- Avoid fixes classes such as "bg-gray-500". Instead, use Shadcn classes such as "bg-background", "text-secondary-foreground", "text-muted-foreground", etc.

Makerkit leverages two sets of UI components:

1. **Shadcn UI Components**: Base components from the Shadcn UI library
2. **Makerkit-specific Components**: Custom components built on top of Shadcn UI

## Importing Components

```tsx
// Import Shadcn UI components
import { Button } from '@kit/ui/button';
import { Card } from '@kit/ui/card';
// Import Makerkit-specific components
import { If } from '@kit/ui/if';
import { ProfileAvatar } from '@kit/ui/profile-avatar';
import { toast } from '@kit/ui/sonner';
import { Trans } from '@kit/ui/trans';
```

## Core Shadcn UI Components

| Component        | Description                               | Import Path                                                                                     |
| ---------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `Accordion`      | Expandable/collapsible content sections   | `@kit/ui/accordion` [accordion.tsx](mdc:packages/ui/src/shadcn/accordion.tsx)                   |
| `AlertDialog`    | Modal dialog for important actions        | `@kit/ui/alert-dialog` [alert-dialog.tsx](mdc:packages/ui/src/shadcn/alert-dialog.tsx)          |
| `Alert`          | Status/notification messages              | `@kit/ui/alert` [alert.tsx](mdc:packages/ui/src/shadcn/alert.tsx)                               |
| `Avatar`         | User profile images with fallback         | `@kit/ui/avatar` [avatar.tsx](mdc:packages/ui/src/shadcn/avatar.tsx)                            |
| `Badge`          | Small status indicators                   | `@kit/ui/badge` [badge.tsx](mdc:packages/ui/src/shadcn/badge.tsx)                               |
| `Breadcrumb`     | Navigation path indicators                | `@kit/ui/breadcrumb` [breadcrumb.tsx](mdc:packages/ui/src/shadcn/breadcrumb.tsx)                |
| `Button`         | Clickable action elements                 | `@kit/ui/button` [button.tsx](mdc:packages/ui/src/shadcn/button.tsx)                            |
| `Calendar`       | Date picker and date display              | `@kit/ui/calendar` [calendar.tsx](mdc:packages/ui/src/shadcn/calendar.tsx)                      |
| `Card`           | Container for grouped content             | `@kit/ui/card` [card.tsx](mdc:packages/ui/src/shadcn/card.tsx)                                  |
| `Checkbox`       | Selection input                           | `@kit/ui/checkbox` [checkbox.tsx](mdc:packages/ui/src/shadcn/checkbox.tsx)                      |
| `Command`        | Command palette interface                 | `@kit/ui/command` [command.tsx](mdc:packages/ui/src/shadcn/command.tsx)                         |
| `DataTable`      | Table                                     | `@kit/ui/data-table` [data-table.tsx](mdc:packages/ui/src/shadcn/data-table.tsx)                |
| `Dialog`         | Modal window for focused interactions     | `@kit/ui/dialog` [dialog.tsx](mdc:packages/ui/src/shadcn/dialog.tsx)                            |
| `DropdownMenu`   | Menu triggered by a button                | `@kit/ui/dropdown-menu` [dropdown-menu.tsx](mdc:packages/ui/src/shadcn/dropdown-menu.tsx)       |
| `Form`           | Form components with validation           | `@kit/ui/form` [form.tsx](mdc:packages/ui/src/shadcn/form.tsx)                                  |
| `Input`          | Text input field                          | `@kit/ui/input` [input.tsx](mdc:packages/ui/src/shadcn/input.tsx)                               |
| `Input OTP`      | OTP Text input field                      | `@kit/ui/input-otp` [input-otp.tsx](mdc:packages/ui/src/shadcn/input-otp.tsx)                   |
| `Label`          | Text label for form elements              | `@kit/ui/label` [label.tsx](mdc:packages/ui/src/shadcn/label.tsx)                               |
| `NavigationMenu` | Hierarchical navigation component         | `@kit/ui/navigation-menu` [navigation-menu.tsx](mdc:packages/ui/src/shadcn/navigation-menu.tsx) |
| `Popover`        | Floating content triggered by interaction | `@kit/ui/popover` [popover.tsx](mdc:packages/ui/src/shadcn/popover.tsx)                         |
| `RadioGroup`     | Radio button selection group              | `@kit/ui/radio-group` [radio-group.tsx](mdc:packages/ui/src/shadcn/radio-group.tsx)             |
| `ScrollArea`     | Customizable scrollable area              | `@kit/ui/scroll-area` [scroll-area.tsx](mdc:packages/ui/src/shadcn/scroll-area.tsx)             |
| `Select`         | Dropdown selection menu                   | `@kit/ui/select` [select.tsx](mdc:packages/ui/src/shadcn/select.tsx)                            |
| `Separator`      | Visual divider between content            | `@kit/ui/separator` [separator.tsx](mdc:packages/ui/src/shadcn/separator.tsx)                   |
| `Sheet`          | Sliding panel from screen edge            | `@kit/ui/sheet` [sheet.tsx](mdc:packages/ui/src/shadcn/sheet.tsx)                               |
| `Sidebar`        | Advanced sidebar navigation               | `@kit/ui/shadcn-sidebar` [sidebar.tsx](mdc:packages/ui/src/shadcn/sidebar.tsx)                  |
| `Skeleton`       | Loading placeholder                       | `@kit/ui/skeleton` [skeleton.tsx](mdc:packages/ui/src/shadcn/skeleton.tsx)                      |
| `Switch`         | Toggle control                            | `@kit/ui/switch` [switch.tsx](mdc:packages/ui/src/shadcn/switch.tsx)                            |
| `Toast`          | Toaster                                   | `@kit/ui/sonner` [sonner.tsx](mdc:packages/ui/src/shadcn/sonner.tsx)                            |
| `Tabs`           | Tab-based navigation                      | `@kit/ui/tabs` [tabs.tsx](mdc:packages/ui/src/shadcn/tabs.tsx)                                  |
| `Textarea`       | Multi-line text input                     | `@kit/ui/textarea` [textarea.tsx](mdc:packages/ui/src/shadcn/textarea.tsx)                      |
| `Tooltip`        | Contextual information on hover           | `@kit/ui/tooltip` [tooltip.tsx](mdc:packages/ui/src/shadcn/tooltip.tsx)                         |

## Makerkit-specific Components

| Component              | Description                         | Import Path                                                                                       |
| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `If`                   | Conditional rendering component     | `@kit/ui/if` [if.tsx](mdc:packages/ui/src/makerkit/if.tsx)                                        |
| `Trans`                | Internationalization text component | `@kit/ui/trans` [trans.tsx](mdc:packages/ui/src/makerkit/trans.tsx)                               |
| `Page`                 | Page layout with navigation         | `@kit/ui/page` [page.tsx](mdc:packages/ui/src/makerkit/page.tsx)                                  |
| `GlobalLoader`         | Full-page loading indicator         | `@kit/ui/global-loader` [global-loader.tsx](mdc:packages/ui/src/makerkit/global-loader.tsx)       |
| `ImageUploader`        | Image upload component              | `@kit/ui/image-uploader` [image-uploader.tsx](mdc:packages/ui/src/makerkit/image-uploader.tsx)    |
| `ProfileAvatar`        | User avatar with fallback           | `@kit/ui/profile-avatar` [profile-avatar.tsx](mdc:packages/ui/src/makerkit/profile-avatar.tsx)    |
| `DataTable` (Enhanced) | Extended data table with pagination | `@kit/ui/enhanced-data-table` [data-table.tsx](mdc:packages/ui/src/makerkit/data-table.tsx)       |
| `Stepper`              | Multi-step process indicator        | `@kit/ui/stepper` [stepper.tsx](mdc:packages/ui/src/makerkit/stepper.tsx)                         |
| `CookieBanner`         | GDPR-compliant cookie notice        | `@kit/ui/cookie-banner` [cookie-banner.tsx](mdc:packages/ui/src/makerkit/cookie-banner.tsx)       |
| `CardButton`           | Card-styled button                  | `@kit/ui/card-button` [card-button.tsx](mdc:packages/ui/src/makerkit/card-button.tsx)             |
| `MultiStepForm`        | Form with multiple steps            | `@kit/ui/multi-step-form` [multi-step-form.tsx](mdc:packages/ui/src/makerkit/multi-step-form.tsx) |
| `EmptyState`           | Empty data placeholder              | `@kit/ui/empty-state` [empty-state.tsx](mdc:packages/ui/src/makerkit/empty-state.tsx)             |
| `AppBreadcrumbs`       | Application path breadcrumbs        | `@kit/ui/app-breadcrumbs` [app-breadcrumbs.tsx](mdc:packages/ui/src/makerkit/app-breadcrumbs.tsx) |

## Marketing Components

Import all marketing components with:

```tsx
import {
  GradientText,
  // etc.
  Hero,
  HeroTitle,
} from '@kit/ui/marketing';
```

Key marketing components:

- `Hero` - Hero sections [hero.tsx](mdc:packages/ui/src/makerkit/marketing/hero.tsx)
- `SecondaryHero` [secondary-hero.tsx](mdc:packages/ui/src/makerkit/marketing/secondary-hero.tsx)
- `FeatureCard`, `FeatureGrid` - Feature showcases [feature-card.tsx](mdc:packages/ui/src/makerkit/marketing/feature-card.tsx)
- `Footer` - Page Footer [footer.tsx](mdc:packages/ui/src/makerkit/marketing/footer.tsx)
- `Header` - Page Header [header.tsx](mdc:packages/ui/src/makerkit/marketing/header.tsx)
- `NewsletterSignup` - Email collection [newsletter-signup-container.tsx](mdc:packages/ui/src/makerkit/marketing/newsletter-signup-container.tsx)
- `ComingSoon` - Coming soon page template [coming-soon.tsx](mdc:packages/ui/src/makerkit/marketing/coming-soon.tsx)
