---
title: Icon
description: Render decorative or named icons from utility names or JSX.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Icon

> Render decorative or named icons from utility names or JSX.

## Anatomy

```text
Icon [component; slot=root; <span>]
```

## Usage

Use Icon for decoration or a named symbol alongside text. If the icon alone conveys meaning, give it
an accessible name; otherwise it is hidden from assistive technology.

```tsx
import { Icon } from 'moraine'

export function Example() {
  return <Icon name="i-lucide:check" />
}
```

### Icon sources

Pass an icon class name, a JSX element, or a Solid component as `name`. Use `icon-search` or
`icon-success` for Moraine's semantic aliases. Editor completion suggests the built-in names, while
`i-lucide-search` and `app-logo` remain valid. `Icon` applies string names as classes, so your
UnoCSS or Tailwind setup must generate the CSS for custom names.

Solid control-flow nodes such as `<Show>`, `<For>`, and `<Switch>` are not supported as the
top-level `name` value. Keep control flow outside `Icon` so it owns whether the component is
rendered.

```tsx
<Icon name="icon-search" />
<Show when={visible()}>
  <Icon name={<StatusGlyph />} />
</Show>
```

### Root styling

`Icon` always renders one `span` root, whatever the `name` source. Use `class` and `style` for an
individual icon, or configure `icon.base.root` in your Theme for shared defaults. `root` is the only
slot, so `classes` and `styles` only duplicate `class` and `style`.

Every icon follows the surrounding font size. A string icon is sized by its icon class, which is
`1.2em` in `moraine/icon.css`. For a JSX or component graphic, the root is a `1.2em` box
(`size-[1.2em]`) and the graphic fills it through `*:size-full`. Resize an icon with a
font-size utility on the icon or an ancestor, such as `text-2xl`, or with a size utility such as
`size-6` on the icon; the graphic follows the root. `moraine/icon.css` puts its rules in the
`components` cascade layer, so these utilities override it in both UnoCSS and Tailwind.

Icon renders no `data-slot` of its own. Pass a `data-slot` attribute when the icon fills a
component slot.

```tsx
<Icon name="i-lucide:info" class="text-2xl text-blue-500" data-slot="custom-icon" />
```

### Forced colors

String icons are CSS masks painted with `background-color: currentColor`. In forced colors mode
(such as Windows contrast themes) the browser would replace that background with the page
background and hide the icon. For string icons, Icon adds the `icon-mask` class, which sets
`forced-color-adjust: preserve-parent-color` (falling back to `none`) and drops its own color, so
the icon is painted with the surrounding forced text color. `presetMoraine` defines `icon-mask` as a
shortcut and the Tailwind plugin defines it as a utility. Element and component icons keep the browser's default forced colors handling.

## Examples

### Mark deploy status with class names

Use Moraine aliases such as `icon-success`, or any class your UnoCSS or Tailwind setup generates
(`i-lucide:git-branch`). Adjacent text is the accessible name when the icon is decoration.

```tsx
import { Icon } from 'moraine'

export function Sources() {
  return (
    <div class="text-sm flex flex-wrap gap-4 items-center">
      <span class="flex gap-1.5 items-center">
        <Icon name="icon-success" />
        Ready
      </span>
      <span class="flex gap-1.5 items-center">
        <Icon name="i-lucide:git-branch" />
        main
      </span>
      <span class="text-muted-foreground flex gap-1.5 items-center">
        <Icon name="i-lucide:clock" />
        Queued
      </span>
    </div>
  )
}
```

### Render a custom SVG glyph

Pass a JSX element or a Solid component when the mark is not an icon-class name. It renders inside
the Icon root. Components are rendered without props: `class`, `style`, `data-slot`, and ARIA
attributes go to the root, and the SVG inherits its color through `currentColor`. To set an
SVG-specific attribute such as `stroke-width`, pass inline JSX instead. Name the icon when it is the
only indicator.

```tsx
import { Icon } from 'moraine'

// Rendered without props; Icon applies class and ARIA attributes to its own root.
function BoltGlyph() {
  return (
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
      <path d="M13 2 3 14h9l-1 8 10-12h-9l1-8z" />
    </svg>
  )
}

export function IconAsJSX() {
  return (
    <div class="flex gap-4 items-center">
      <Icon
        name={
          <svg
            viewBox="0 0 24 24"
            width="24"
            height="24"
            fill="none"
            stroke="currentColor"
            stroke-width="2"
          >
            <circle cx="12" cy="12" r="10" />
            <path d="M8 14s1.5 2 4 2 4-2 4-2" />
            <line x1="9" y1="9" x2="9.01" y2="9" />
            <line x1="15" y1="9" x2="15.01" y2="9" />
          </svg>
        }
        class="size-6"
        aria-label="Status"
      />
      <Icon name={BoltGlyph} class="size-6" aria-label="Boost" />
    </div>
  )
}
```

### Name a warning and hide a decorative check

Keep adjacent text as the name when the icon is decoration. Set `aria-label` when the icon is the
only indicator.

```tsx
import { Icon } from 'moraine'

export function Accessibility() {
  return (
    <div class="flex gap-5 items-center">
      <p class="text-sm flex gap-2 items-center">
        <Icon name="i-lucide:circle-check" aria-hidden="true" class="text-success" />
        Changes saved
      </p>
      <Icon name="i-lucide:triangle-alert" aria-label="Warning" class="text-warning size-5" />
    </div>
  )
}
```

## API Reference

### Props

Props for the Icon component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name* | Name | — | Icon source. Strings should be Uno icon classes such as `i-lucide-search`<br>or app-config aliases such as `icon-search`.<br>Non-string values can be JSX nodes or Solid components. They render inside the host and<br>fill it; components are rendered without props, and every Icon prop goes to the host.<br>Wrap Icon in Solid control flow instead of passing a control-flow node as `name`. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`name` example**

```tsx
import { Icon } from 'moraine'

<div class="flex gap-2 text-xl">
  <Icon name="i-lucide-search" />
  <Icon name={<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /></svg>} />
  <Icon name={() => <span>★</span>} />
</div>
```
