> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rixxui.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Icons

> Use the default semantic Lucide icons or extend and replace them with trusted React icon components from your design system.

Rixx UI uses semantic icon names rather than library-specific names. The default
registry is implemented with a curated Lucide set, while generated RUI stays
independent from Lucide.

```rui theme={null}
root = Stack(children=[status,next], direction="row", gap="sm")
status = Icon(name="status.success", label="Complete", tone="success")
next = Button(label="Continue", icon="navigation.forward", action="flow.next")
```

The same active registry validates `Icon.name`, `Button.icon`, and
`EmptyState.icon`. Unknown names produce compiler diagnostics and are not
replaced with a misleading fallback icon.

## Default semantic icons

* Actions: `action.add`, `action.close`, `action.copy`, `action.delete`,
  `action.download`, `action.edit`, `action.refresh`, `action.search`,
  `action.settings`, `action.upload`
* Navigation: `navigation.back`, `navigation.external`, `navigation.forward`,
  `navigation.home`, `navigation.menu`
* Status: `status.danger`, `status.info`, `status.success`, `status.warning`
* Content: `content.calendar`, `content.chart`, `content.code`,
  `content.document`, `content.image`, `content.link`, `content.mail`,
  `content.user`
* Security: `security.lock`, `security.unlock`
* Other: `concept.ai`, `trend.decrease`, `trend.increase`

Directional navigation icons mirror automatically in RTL layouts.

## Extend the defaults

```tsx theme={null}
import { Workspace } from "@acme/icons";
import {
  defaultIconRegistry,
  defineIconRegistry,
  defineRUI,
} from "@rixx-ui/react";

const icons = defineIconRegistry({
  id: "acme.semantic-icons@1",
  extend: defaultIconRegistry,
  icons: {
    "product.workspace": {
      description: "A product workspace",
      glyph: Workspace,
    },
  },
});

export const rui = defineRUI({ catalog, registry, iconRegistry: icons });
```

The generated schema and `rui.instructions(prompt)` automatically include the
extended vocabulary.

## Replace the defaults

Omit `extend` to expose only your own icons. Registry names must use semantic
dot notation, descriptions are required, and glyphs must be trusted React SVG
components. Rixx UI never dynamically imports an icon selected by a model.

Standalone informative icons need a concise `label`. Icons beside visible button
text remain decorative to assistive technology.


## Related topics

- [@rixx-ui/react API](/reference/react.md)
- [Core components](/reference/core-components.md)
- [Changelog](/project/changelog.md)