# Icon

Render Iconify icons in Astro and MDX content.

import { Callout, Icon } from '@prosefly/astro-components';

Use `Icon` for small visual cues in content: card icons, inline labels, and
status descriptions. Use the `prefix:name` format from Iconify, such as
`lucide:sparkles` or `simple-icons:github`.

## Import

```mdx
import { Icon } from '@prosefly/astro-components';
```

## Inline Icons

<p><Icon name="lucide:sparkles" /> Reusable MDX components for Astro documentation.</p>

```mdx
<p><Icon name="lucide:sparkles" /> Reusable MDX components for Astro documentation.</p>
```

## Accessible Icons

Decorative icons are hidden from assistive technology by default. Add `title`
when the icon itself carries meaning.

<p><Icon name="lucide:triangle-alert" title="Warning" /> Check the setup before continuing.</p>

```mdx
<p><Icon name="lucide:triangle-alert" title="Warning" /> Check the setup before continuing.</p>
```

## Icon Integration

Register the `proseflyComponents()` integration when a standalone Astro project needs
Iconify scanning and preloading.

```ts title="astro.config.ts"
import { defineConfig } from 'astro/config';
import proseflyComponents from '@prosefly/astro-components/integration';

export default defineConfig({
  integrations: [
    proseflyComponents({
      icons: {
        preload: ['lucide:sparkles', 'simple-icons:github'],
      },
    }),
  ],
});
```

The integration always includes icons used internally by the package components.
It also scans `src/**/*.astro`, `src/**/*.md`, and `src/**/*.mdx` for static
`name` and `icon` prop values by default. Add dynamic icon names to `preload`,
because the scanner only sees literal strings.

| Option | Type | Default |
| --- | --- | --- |
| `preload` | `string[]` | `[]` |
| `scan` | `boolean` | `true` |
| `apiBase` | `string` | `https://api.iconify.design` |

Set `scan: false` when a site should preload only the icons listed in
`preload`, or set `apiBase` to use an internal Iconify-compatible endpoint.

### Caching

Preloading and on-demand rendering share a per-icon cache. Overlapping requests
reuse in-flight work, and preload batches fetch only icons that are not already
cached. The cache separates API endpoints and icon sets.

Successful responses are also persisted in `.astro/prosefly/icons` under the
working directory for **7 days**, so restarting development or rebuilding does
not download those icons again until they expire. Set `PROSEFLY_ICON_CACHE_DIR`
to use a different directory. For fresh data before expiry, stop the process,
remove that cache directory, and restart.

Corrupt or expired cache files are ignored. If disk caching is unavailable,
in-memory caching still works. Failed requests are not cached; the next render
or preload attempt retries them.

An integration-level `apiBase` is also used by on-demand icons, unless an `Icon`
explicitly supplies its own `apiBase`.

<Callout type="note" title="Prosefly theme defaults">
  [Dahlia](https://astro-theme-dahlia.prosefly.dev/) and
  [Lotus](https://astro-theme-lotus.prosefly.dev/) already register the shared
  integration and scan `src/**/*.astro`, `src/**/*.md`, and `src/**/*.mdx` for
  static icon names. Theme projects do not need another `proseflyComponents()` entry.
</Callout>

## Props

| Prop | Type | Default |
| --- | --- | --- |
| `name` | `string` | required |
| `title` | `string` | none |
| `size` | `number \| string` | none |
| `width` | `number \| string` | `size ?? '1em'` |
| `height` | `number \| string` | `size ?? '1em'` |
| `apiBase` | `string` | Integration's `apiBase`, or `https://api.iconify.design` |