Skip to main content

Icon

Render decorative or named icons from utility names or JSX.

Props
Slots

Anatomy#

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.

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.

<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.

<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.

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.

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.

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. Renders a <span> element by default.

Prop