# Utilities

> Helper components for conditional rendering, translations, and theming.

*Canonical: https://makerkit.dev/docs/tanstack-drizzle/ui-components/utilities*

---

Utility components for common patterns like conditional rendering, internationalization, and theme management.

## If

Conditional rendering component with type inference.

```typescript
import { If } from '@kit/ui/if';
```

```tsx
{/* Basic usage */}
<If condition={isLoading} fallback={<Content />}>
  <Spinner />
</If>

{/* With type inference */}
<If condition={error}>
  {(err) => <ErrorMessage error={err} />}
</If>

{/* Render prop pattern */}
<If condition={user}>
  {(user) => <UserProfile user={user} />}
</If>
```

## Trans

Translation component for internationalization.

```typescript
import { Trans } from '@kit/ui/trans';
```

```tsx
{/* Simple translation */}
<Trans i18nKey="common.welcome" />

{/* With variables */}
<Trans
  i18nKey="user.greeting"
  values={{ name: user.name }}
/>

{/* With default text */}
<Trans
  i18nKey="common.submit"
  defaults="Submit"
/>

{/* Rich text with components */}
<Trans
  i18nKey="terms.agreement"
  components={{
    TermsLink: <a href="/terms" className="underline" />,
    PrivacyLink: <a href="/privacy" className="underline" />,
  }}
/>
```

## Lazy Render

Lazy load content when visible using IntersectionObserver.

```typescript
import { LazyRender } from '@kit/ui/lazy-render';
```

```tsx
<LazyRender>
  <HeavyComponent />
</LazyRender>

{/* With options */}
<LazyRender
  threshold={0.5}
  rootMargin="100px"
  onVisible={() => console.log('Component visible')}
>
  <ExpensiveChart />
</LazyRender>
```

## Error Boundary

Catch and handle React errors.

```typescript
import { ErrorBoundary } from '@kit/ui/error-boundary';
```

```tsx
<ErrorBoundary
  fallback={
    <Alert variant="destructive">
      <AlertTitle>Something went wrong</AlertTitle>
      <AlertDescription>
        Please refresh the page.
      </AlertDescription>
    </Alert>
  }
>
  <ComponentThatMightError />
</ErrorBoundary>
```

## Stepper

Multi-step progress indicator.

```typescript
import { Stepper } from '@kit/ui/stepper';
```

```tsx
<Stepper
  steps={['Account', 'Profile', 'Review']}
  currentStep={1}
/>

{/* Numbers variant */}
<Stepper
  steps={['Step 1', 'Step 2', 'Step 3']}
  currentStep={2}
  variant="numbers"
/>

{/* Dots variant */}
<Stepper
  steps={['', '', '', '']}
  currentStep={0}
  variant="dots"
/>
```

## Mode Toggle

Dark/light theme switcher.

```typescript
import { ModeToggle } from '@kit/ui/mode-toggle';
```

```tsx
<ModeToggle />
```

### Sub Menu Variant

```typescript
import { SubMenuModeToggle } from '@kit/ui/mode-toggle';
```

```tsx
<SubMenuModeToggle />
```

### Theme Preference Card

```typescript
import { ThemePreferenceCard } from '@kit/ui/mode-toggle';
```

```tsx
<ThemePreferenceCard currentTheme="system" />
```

Displays cards for Light, Dark, and System theme options. The `currentTheme` prop sets the initial theme value.

## Cookie Banner

GDPR cookie consent banner.

```typescript
import { CookieBanner, useCookieConsent } from '@kit/ui/cookie-banner';
```

```tsx
<CookieBanner />
```

### Using Consent Hook

```tsx
const { status, accept, reject, clear } = useCookieConsent();

// status: 'unknown' | 'accepted' | 'rejected'
```

## Language Selector

Language/locale switcher.

```typescript
import { LanguageSelector, LanguagePreferenceCard } from '@kit/ui/language-selector';
```

```tsx
// Locale switching is handled internally (cookie-based via useChangeLocale).
// Optionally react to a change with onChange.
<LanguageSelector
  locales={['en', 'de', 'es']}
  onChange={(locale) => console.log('Selected locale:', locale)}
/>
```

### Language Preference Card

Card UI for language selection in settings pages.

```tsx
<LanguagePreferenceCard locales={['en', 'de', 'es']} />
```

## cn Utility

Class name merging utility.

```typescript
import { cn } from '@kit/ui/utils';
```

```tsx
<div className={cn(
  'base-classes',
  isActive && 'active-classes',
  className
)}>
  Content
</div>
```

---

**Next:** [Marketing →](./marketing)
