Primitives

Icon

Thin wrapper around lucide-react icons that maps a tone prop to Clay's semantic icon-color tokens.

Preview

import { Icon } from '@brika/clay/components/icon';
import { Bell } from 'lucide-react';

/** Decorative icon, no `aria-label`, so screen readers skip it entirely. */
export default function IconDefaultDemo() {
  return <Icon as={Bell} />;
}

01 Installation

Install

Pull Icon from the barrel for everyday use, or the granular path when you want a tighter bundle.

tsxBarrel1 line

import { Icon } from "@brika/clay";

tsxGranular1 line

import { Icon } from "@brika/clay/components/icon";

02 Usage

A minimal example

Drop this into a page. Native HTML attributes pass through to the underlying primitive.

tsxIcon.tsx7 lines

import { Icon } from '@brika/clay/components/icon';
import { Bell } from 'lucide-react';

/** Decorative icon, no `aria-label`, so screen readers skip it entirely. */
export default function IconDefaultDemo() {
  return <Icon as={Bell} />;
}

03 Examples

Icon, every way

Accessible

`aria-label` makes the icon meaningful, screen readers announce the label text.

GitHub

import { Icon } from '@brika/clay/components/icon';
import { Bell, Star, User } from 'lucide-react';

/** `aria-label` makes the icon meaningful, screen readers announce the label text. */
export default function IconAccessibleDemo() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Icon as={Bell} aria-label="Notifications" tone="primary" />
      <Icon as={Star} aria-label="Starred items" tone="muted" />
      <Icon as={User} aria-label="User profile" />
    </div>
  );
}

Sizes

Four size presets mapping to Tailwind `size-*` utilities.

GitHub

import { Icon } from '@brika/clay/components/icon';
import { Bell } from 'lucide-react';

/** Four size presets mapping to Tailwind `size-*` utilities. */
export default function IconSizesDemo() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Icon as={Bell} size="xs" aria-label="Extra small notification" />
      <Icon as={Bell} size="sm" aria-label="Small notification" />
      <Icon as={Bell} size="default" aria-label="Default notification" />
      <Icon as={Bell} size="lg" aria-label="Large notification" />
    </div>
  );
}

Tones

Three semantic tones mapped to `--icon`, `--icon-muted`, and `--icon-primary`.

GitHub

import { Icon } from '@brika/clay/components/icon';
import { Bell } from 'lucide-react';

/** Three semantic tones mapped to `--icon`, `--icon-muted`, and `--icon-primary`. */
export default function IconTonesDemo() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <div className="flex items-center gap-2">
        <Icon as={Bell} tone="default" />
        <span className="text-sm">Default</span>
      </div>
      <div className="flex items-center gap-2">
        <Icon as={Bell} tone="muted" />
        <span className="text-sm text-muted-foreground">Muted</span>
      </div>
      <div className="flex items-center gap-2">
        <Icon as={Bell} tone="primary" />
        <span className="text-sm text-primary">Primary</span>
      </div>
    </div>
  );
}

04 Accessibility

Accessibility

Decorative by default, aria-hidden="true" is set when no aria-label is provided.
Pass aria-label to make the icon carry standalone meaning (e.g. status indicator).
Do not use an icon alone as a button label, always pair with aria-label on the button.

05 Tokens 3 theme-overridable

Theme tokens

Every CSS variable Icon reads, with its default and the dotted path you'd write in a ThemeConfig JSON to override it. Set any of these in your theme to retune Icon without touching component code.

Icon tokens

3 tokens

ColorFill, border, and text colors.3

--icon-mutedcolorvar(--muted-foreground)
components.icon.muted
Muted icon color.
--icon-primarycolorvar(--primary)
components.icon.primary
Primary icon color (interactive accents).
--iconcolorvar(--foreground)
components.icon.default
Default icon color.

Override in a theme

Authoring a theme is plain JSON. Drop overrides under components.icon, the names are camelCase versions of the variable suffix.

jsonmy-theme.json12 lines

{
  "id": "my-theme",
  "name": "My Theme",
  "description": "...",
  "accentSwatches": ["#000"],

  "components": {
    "icon": {
      "muted": "var(--muted-foreground)"
    }
  }
}

Then apply with applyTheme(myTheme) (see the theming guide), scope it to a subtree with themeToCssVars(myTheme, mode), or consume any token directly in your own JSX with the matching Tailwind utility (e.g. bg-icon-…) — see the chips on each token row.

06 API reference

API reference

Props specific to Icon. Native HTML attributes pass through to the underlying primitive, see the component source on GitHub for the full type signature.

as*
IconComponent
The icon component to render. Typically a lucide-react icon (e.g. Bell, AlertCircle) but any React.ComponentType that accepts SVGProps<SVGSVGElement> is supported.
className
string
Extra class names merged onto the rendered SVG. Use this to override defaults or compose layout utilities, Clay merges with tailwind-merge so the caller's classes win on conflict.
sizedefault 'default'
IconSize
Visual size of the icon. Maps to Tailwind size-* utilities (xs → 0.75rem, sm → 0.875rem, default → 1rem, lg → 1.25rem). Defaults to 'default'.
tonedefault 'default'
IconTone
Semantic color of the icon, mapped to one of Clay's icon-color tokens (--icon, --icon-muted, --icon-primary). Defaults to 'default'.