# Icon

Renders a Mosaic glyph, hidden from assistive tech. A glyph can be swapped by name through the `icons` prop on `MosaicProvider`, and the override gets the same sizing. `IconFrame` is a square box that frames an icon or image.

## Use for

- an icon in a button, row or label
- a leading or trailing icon in a button
- a framed icon tile

## Practices

- Do: Set `placement` when the icon leads or trails a `Button` label, so the button tightens that side.
- Do: Use `size='inherit'` for an icon in running text or a heading.
- Don't: Rely on the icon for the accessible name. It renders `aria-hidden`; name the control with text or `aria-label`.
- Don't: Expect `ref` to reach an icon swapped through `MosaicProvider`. It only reaches the built-in glyph.

## API reference

### Icon

Renders the `glyph` as an `svg`, or its override. Takes its color from `currentColor` unless the container sets one.

Slot: `cl-icon`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `glyph` | `IconComponent` |  | The glyph component, from `src/icons/glyphs`. |
| `size` | `'sm' \| 'md' \| 'lg' \| 'inherit'` | `'md'` | `sm`, `md`, `lg`, or `inherit` to follow the font size. |
| `placement` | `'inline-start' \| 'inline-end'` |  | Marks the icon as leading or trailing content, as `data-icon`. Applies no style of its own. |

### IconFrame

A square `span` that centers its content, sized to the media scale.

Slot: `cl-icon-frame`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bordered` | `boolean` | `true` | Draws a subtle border. |
| `filled` | `boolean` | `false` | Fills the box with a neutral tint. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | `xs`, `sm`, `md` or `lg`. |

## Examples

### A trailing icon in a button

```tsx
<Button>
  Next
  <Icon glyph={ChevronRight} placement='inline-end' />
</Button>
```

## Related

- [Button](/docs/components/button.md)
- `MosaicProvider`
