Icon

Icon is Rayden’s SVG-rendering component. Individual exports such as heartIcon are icon data, not React components. Each registered icon has outline and solid variants.

Import and render

import { Icon, iconCatalog, iconNames } from "@raydenui/ui";
import type { IconProps, IconName, IconRecord, IconSource, IconSize, IconVariant } from "@raydenui/ui";
import { heartIcon } from "@raydenui/ui/icons";
 
// Direct data: immediate rendering, including server-rendered HTML.
<Icon icon={heartIcon} variant="solid" size="lg" />;
 
// Registry name: convenient lookup, loaded after mounting in the browser.
<Icon name="heart" variant="outline" size={24} />;

Pass exactly one of name or icon. A name is a registry key such as arrow-down; a data export is its exact JavaScript identifier such as arrowDownIcon. Existing acronym and numeric names retain their original spelling; use the catalog instead of guessing an export name. Do not render data as <heartIcon /> or pass a string to icon.

The name API reserves the SVG’s size while the registry loads. A bundler with code splitting can load that registry separately. For initial HTML and tree shaking, import individual data records. Do not import the combined icons registry unless you need the whole collection.

Discover the icons

iconCatalog is generated from the real registry and contains every { name, exportName } pair, without SVG artwork. iconNames is the corresponding readonly list of names. Both are available from the root package and @raydenui/ui/icons.

const matches = iconCatalog.filter(({ name, exportName }) =>
  `${name} ${exportName}`.toLowerCase().includes("arrow")
);
// Example entry: { name: "arrow-down", exportName: "arrowDownIcon" }

Open Components → Icon → Gallery in Storybook to search by name or export and compare outline/solid artwork. AI clients can find the same generated mapping at catalog.icons.entries in /ai/catalog.json.

Shared icon slots

Icon slots on Button, Input, SelectOption, DropdownMenuItem, Modal and other components using IconSource accept the same three forms: a registry name, static IconRecord, or a custom React node.

import { Button, Input, Icon } from "@raydenui/ui";
import { checkIcon, searchIcon, heartIcon } from "@raydenui/ui/icons";
 
<Button icon="check" iconPosition="leading">Save</Button>;
<Button icon={checkIcon} iconPosition="leading">Save</Button>;
<Input label="Search" leadingIcon={searchIcon} />;
<Button icon={<Icon icon={heartIcon} variant="solid" />} iconPosition="leading">
  Favorite
</Button>;

Names and direct records use the slot’s default size and the outline variant. Pass an Icon element for a solid variant, custom size, or custom SVG attributes. Custom nodes retain their own props. Slot names describe placement (leadingIcon, trailingIcon) or purpose (icon); they use the same value convention.

Props

Preset sizes are xs = 12px, sm = 16px, md = 20px, lg = 24px, and xl = 32px. Use size={40} or size={48} for larger sizes; 2xl and 3xl are not preset names. Native SVG attributes and refs are forwarded.

Accessibility

Icons are decorative by default (aria-hidden="true"). Label the action on its button or link:

<Button icon="multiply" iconPosition="icon-only" aria-label="Close dialog" />

For a standalone icon that communicates meaning, explicitly expose and name it:

<Icon icon={checkIcon} aria-hidden={false} role="img" aria-label="Completed" />

An aria-label alone does not override the default aria-hidden. Use a real button or link for interactive icons.