### Install Dependencies and Build

Source: https://github.com/ionic-team/ionicons/blob/main/CONTRIBUTING.md

Install project dependencies using npm and run the initial build. This ensures your development environment is set up correctly.

```bash
npm install
npm run build
```

--------------------------------

### Install and Use LTS Node.js Version

Source: https://github.com/ionic-team/ionicons/blob/main/CONTRIBUTING.md

Installs the latest Long Term Support (LTS) version of Node.js and sets it as the active version. This is a common step in environment setup.

```bash
nvm install --lts && nvm use --lts
```

--------------------------------

### Clone and Setup Ionicons Repository

Source: https://github.com/ionic-team/ionicons/blob/main/CONTRIBUTING.md

Clone your fork of the Ionicons repository and set up the upstream remote. This is the first step in setting up your local development environment.

```bash
git clone https://github.com/YOUR-USERNAME/ionicons.git
cd ionicons
git remote add upstream https://github.com/ionic-team/ionicons.git
```

--------------------------------

### Install Ionicons via NPM

Source: https://context7.com/ionic-team/ionicons/llms.txt

Install the ionicons package for use in bundled projects like React, Vue, or Angular.

```bash
npm install ionicons
```

--------------------------------

### Preview ion-icon Component Locally

Source: https://github.com/ionic-team/ionicons/blob/main/scripts/readme.md

Start a local development server to preview the `ion-icon` component in action. This is useful for testing icon rendering and component behavior.

```sh
npm start
```

--------------------------------

### Install Node Version Manager (macOS/Linux)

Source: https://github.com/ionic-team/ionicons/blob/main/CONTRIBUTING.md

Installs nvm, a Node.js version manager, using a curl script. Recommended for managing Node.js versions on macOS and Linux.

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
```

--------------------------------

### Install Ionicons Web Component

Source: https://github.com/ionic-team/ionicons/blob/main/readme.md

Include these scripts to enable the Ionicons web component. Replace 'latest' with a specific version if needed.

```html
<script type="module" src="https://esm.sh/ionicons@latest/loader"></script>
<script nomodule src="https://esm.sh/ionicons@latest/loader"></script>
```

```html
<script type="module" src="https://esm.sh/ionicons@8.0.0/loader"></script>
<script nomodule src="https://esm.sh/ionicons@8.0.0/loader"></script>
```

--------------------------------

### Update Branch from Upstream

Source: https://github.com/ionic-team/ionicons/blob/main/CONTRIBUTING.md

Before starting new work or to keep your branch up-to-date, pull the latest changes from the upstream repository and create a new feature branch.

```bash
git checkout main
git pull upstream main
git checkout -b your-feature-branch
```

--------------------------------

### Internal SVG Sanitization Logic

Source: https://context7.com/ionic-team/ionicons/llms.txt

This TypeScript comment outlines the internal sanitization process: `<script>` elements and attributes starting with 'on' are rejected. Non-SVG root elements are stripped, and a "s-ion-icon" class is appended to valid results.

```typescript
// Internal sanitization logic (for reference)
// <script> elements → rejected entirely
// Attributes starting with "on" (onclick, onmouseover…) → rejected entirely
// Non-SVG root elements → stripped
// Valid result: SVG string with "s-ion-icon" class appended
```

--------------------------------

### Format Code with Prettier

Source: https://github.com/ionic-team/ionicons/blob/main/CONTRIBUTING.md

Run this command to format your code according to the project's Prettier configuration. This should be done before submitting changes.

```bash
npm run prettier
```

--------------------------------

### Load Ionicons from CDN

Source: https://context7.com/ionic-team/ionicons/llms.txt

Load Ionicons directly from a CDN without a build step. Ensure the script tag is placed before the closing `</body>` tag.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Ionicons CDN Example</title>
</head>
<body>

  <!-- Built-in named icon -->
  <ion-icon name="heart"></ion-icon>

  <!-- Outline variant -->
  <ion-icon name="heart-outline"></ion-icon>

  <!-- Sharp variant -->
  <ion-icon name="heart-sharp"></ion-icon>

  <!-- Module-supporting browsers -->
  <script type="module" src="https://esm.sh/ionicons@8.0.13/loader"></script>
  <!-- Legacy browsers -->
  <script nomodule src="https://esm.sh/ionicons@8.0.13/loader"></script>

</body>
</html>
```

--------------------------------

### Build Ionicons Locally

Source: https://github.com/ionic-team/ionicons/blob/main/scripts/readme.md

Run this command after updating, adding, or deleting SVGs in the `src/svg` directory. It optimizes all icons and generates distribution files in the `dist` directory.

```sh
npm run build
```

--------------------------------

### Basic Ionicons Usage

Source: https://github.com/ionic-team/ionicons/blob/main/readme.md

Use the 'name' attribute to display a built-in icon from the Ionicons package.

```html
<ion-icon name="heart"></ion-icon>
```

--------------------------------

### Configure Custom Asset Path and Load Icons

Source: https://github.com/ionic-team/ionicons/blob/main/readme.md

Set the base path for loading custom icons and explicitly add specific icons using 'setAssetPath' and 'addIcons'.

```typescript
import { setAssetPath, addIcons } from 'ionicons';
import { add, logoIonic, save } from 'ionicons/icons';

// set root path for loading icons to "<root>/public/svg"
setAssetPath(`${window.location.origin}/public/svg/`);

// only load specific icons
addIcons({ add, logoIonic, save });
```

--------------------------------

### Set Icon Size

Source: https://context7.com/ionic-team/ionicons/llms.txt

Apply pre-defined size tokens (`small`, `large`) or use CSS for arbitrary sizing. The `font-size` CSS property controls the icon size.

```html
<!-- Pre-defined tokens -->
<ion-icon name="star" size="small"></ion-icon>  <!-- 1.125rem -->
<ion-icon name="star" size="large"></ion-icon>  <!-- 2rem -->

<!-- Custom size via CSS -->
<style>
  .icon-64 { font-size: 64px; }
  .icon-32 { font-size: 32px; }
</style>
<ion-icon name="star" class="icon-64"></ion-icon>
<ion-icon name="star" class="icon-32"></ion-icon>
```

--------------------------------

### Render Built-in Icons by Name

Source: https://context7.com/ionic-team/ionicons/llms.txt

Renders a built-in icon using its kebab-case name. Ionicons automatically resolves the correct SVG asset path.

```html
<!-- filled (default) -->
<ion-icon name="alarm"></ion-icon>

<!-- outline variant -->
<ion-icon name="alarm-outline"></ion-icon>

<!-- sharp variant -->
<ion-icon name="alarm-sharp"></ion-icon>

<!-- Expected output: inline SVG injected into shadow DOM, sized 1em × 1em,
inheriting the parent's color via `fill: currentColor`. -->
```

--------------------------------

### Enable Lazy Loading for `<ion-icon>`

Source: https://context7.com/ionic-team/ionicons/llms.txt

Defer SVG network requests until icons scroll into the viewport by setting `lazy="true"`. This is useful for improving performance in long lists or virtualized tables.

```html
<!-- lazy=false (default): loads immediately -->
<ion-icon name="heart"></ion-icon>

<!-- lazy=true: defers fetch until visible (50px pre-load margin) -->
<ion-icon name="heart" lazy="true"></ion-icon>

<!-- Useful for long lists / virtualized tables -->
<ul>
  <li><ion-icon name="checkmark-circle" lazy="true"></ion-icon> Item 1</li>
  <li><ion-icon name="checkmark-circle" lazy="true"></ion-icon> Item 2</li>
  <!-- ... hundreds more ... -->
</ul>
```

--------------------------------

### Release Ionicons

Source: https://github.com/ionic-team/ionicons/blob/main/scripts/readme.md

Execute the release script to prepare and publish a new version of Ionicons. This script will prompt for versioning and tagging information.

```sh
npm run release
```

--------------------------------

### Rebuild SVG Icon Files

Source: https://github.com/ionic-team/ionicons/blob/main/CONTRIBUTING.md

Use this command to re-run the SVG optimization script. This is useful for verifying changes after optimizing SVGs.

```bash
npm run build.files
```

--------------------------------

### Ionicons Icon Sizing (CSS)

Source: https://github.com/ionic-team/ionicons/blob/main/readme.md

Set a specific icon size using the 'font-size' CSS property. Pixel sizes that are multiples of 8 are recommended.

```css
ion-icon {
  font-size: 64px;
}
```

--------------------------------

### Ionicons Icon Sizing (Pre-defined)

Source: https://github.com/ionic-team/ionicons/blob/main/readme.md

Use the 'size' attribute for pre-defined font sizes like 'small' or 'large'.

```html
<ion-icon size="small"></ion-icon>
<ion-icon size="large"></ion-icon>
```

--------------------------------

### Create a New Feature Branch

Source: https://github.com/ionic-team/ionicons/blob/main/CONTRIBUTING.md

Create a new branch from the main branch to isolate your changes. This is part of the recommended branch strategy for contributions.

```bash
git checkout -b your-feature-branch
```

--------------------------------

### Pre-register Icons with `addIcons`

Source: https://context7.com/ionic-team/ionicons/llms.txt

In custom-elements or tree-shaken builds, use `addIcons` to map icon names (camelCase or kebab-case) to their SVG data-URL strings. This avoids network fetches for icons used in templates.

```typescript
import { addIcons } from 'ionicons';
import { heart, heartOutline, heartSharp, logoIonic, addCircleOutline } from 'ionicons/icons';

// Register specific icons — both camelCase and kebab-case names are accepted
addIcons({
  heart,
  heartOutline,    // also registered as "heart-outline"
  heartSharp,      // also registered as "heart-sharp"
  logoIonic,       // also registered as "logo-ionic"
  addCircleOutline // also registered as "add-circle-outline"
});

// Now usable by name in templates — no network fetch required
// <ion-icon name="heart"></ion-icon>
// <ion-icon name="heart-outline"></ion-icon>
// <ion-icon name="add-circle-outline"></ion-icon>
```

--------------------------------

### Custom Icon Usage

Source: https://github.com/ionic-team/ionicons/blob/main/readme.md

Provide the URL to an external SVG file in the 'src' attribute to use a custom icon. The SVG must be accessible and cannot contain scripts.

```html
<ion-icon src="/path/to/external/file.svg"></ion-icon>
```

--------------------------------

### Display Outline Icon

Source: https://github.com/ionic-team/ionicons/blob/main/readme.md

Use the `name` attribute to specify the icon to display. For outline variants, the stroke width can be adjusted.

```html
<ion-icon name="heart-outline"></ion-icon>
```

--------------------------------

### Ionicon Properties

Source: https://github.com/ionic-team/ionicons/blob/main/src/components/icon/readme.md

This section details the available properties for the ion-icon component, which control its appearance, behavior, and the icon source.

```APIDOC
## Properties

| Property   | Attribute  | Description                                                                                                                                                                                   | Type                   | Default        |
| ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | -------------- |
| `color`    | `color`    | The color to use for the background of the item.                                                                                                                                              | `string \| undefined`  | `undefined`    |
| `flipRtl`  | `flip-rtl` | Specifies whether the icon should horizontally flip when `dir` is `"rtl"`.                                                                                                                    | `boolean \| undefined` | `undefined`    |
| `icon`     | `icon`     | A combination of both `name` and `src`. If a `src` url is detected it will set the `src` property. Otherwise it assumes it's a built-in named SVG and set the `name` property.                | `any`                  | `undefined`    |
| `ios`      | `ios`      | Specifies which icon to use on `ios` mode.                                                                                                                                                    | `string \| undefined`  | `undefined`    |
| `lazy`     | `lazy`     | If enabled, ion-icon will be loaded lazily when it's visible in the viewport. Default, `false`.                                                                                               | `boolean`              | `false`        |
| `md`       | `md`       | Specifies which icon to use on `md` mode.                                                                                                                                                     | `string \| undefined`  | `undefined`    |
| `mode`     | `mode`     | The mode determines which platform styles to use.                                                                                                                                             | `string`               | `getIonMode()` |
| `name`     | `name`     | Specifies which icon to use from the built-in set of icons.                                                                                                                                   | `string \| undefined`  | `undefined`    |
| `sanitize` | `sanitize` | When set to `false`, SVG content that is HTTP fetched will not be checked if the response SVG content has any `<script>` elements, or any attributes that start with `on`, such as `onclick`. | `boolean`              | `true`         |
| `size`     | `size`     | The size of the icon. Available options are: `"small"` and `"large"`.                                                                                                                         | `string \| undefined`  | `undefined`    |
| `src`      | `src`      | Specifies the exact `src` of an SVG file to use.                                                                                                                                              | `string \| undefined`  | `undefined`    |
```

--------------------------------

### Load External SVG Files

Source: https://context7.com/ionic-team/ionicons/llms.txt

Loads any external SVG file by URL using the `src` attribute. Content is sanitized by default unless `sanitize="false"` is set.

```html
<!-- External SVG -->
<ion-icon src="/assets/icons/custom-logo.svg"></ion-icon>

<!-- Base64 / data-URL SVG (works under strict CSP) -->
<ion-icon src="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 512 512'><circle cx='256' cy='256' r='200'/></svg>"></ion-icon>

<!-- Disable sanitization for a trusted internal SVG -->
<ion-icon src="/trusted/icon.svg" sanitize="false"></ion-icon>
```

--------------------------------

### Platform Specific Icons

Source: https://github.com/ionic-team/ionicons/blob/main/readme.md

Specify different icons for iOS and Material Design platforms using the 'ios' and 'md' attributes.

```html
<ion-icon ios="heart-outline" md="heart-sharp"></ion-icon>
```

--------------------------------

### Importing Icons as ES Modules in React

Source: https://context7.com/ionic-team/ionicons/llms.txt

In React, import icons from `ionicons/icons` and pass the icon object directly to the `icon` prop of the `IonIcon` component. You can also specify `ios` and `md` props for platform-specific icons.

```typescript
// React example
import { IonIcon } from '@ionic/react';
import { heart, heartOutline, addCircleOutline } from 'ionicons/icons';

function App() {
  return (
    <div>
      {/* Pass icon object directly to the icon prop */}
      <IonIcon icon={heart} />
      <IonIcon icon={heartOutline} />
      <IonIcon icon={addCircleOutline} size="large" color="primary" />

      {/* Or use ios / md per-platform icons */}
      <IonIcon ios={heartOutline} md={heart} />
    </div>
  );
}
```

--------------------------------

### Apply Color Tokens

Source: https://context7.com/ionic-team/ionicons/llms.txt

Applies Ionic color tokens which map to CSS custom properties. Plain CSS can also be used to override colors.

```html
<ion-icon name="heart" color="primary"></ion-icon>    <!-- #3880ff -->
<ion-icon name="heart" color="secondary"></ion-icon>  <!-- #0cd1e8 -->
<ion-icon name="heart" color="danger"></ion-icon>     <!-- #f14141 -->
<ion-icon name="heart" color="success"></ion-icon>    <!-- #10dc60 -->
<ion-icon name="heart" color="warning"></ion-icon>    <!-- #ffce00 -->
<ion-icon name="heart" color="dark"></ion-icon>       <!-- #222428 -->

<!-- Override via plain CSS (works without Ionic color tokens) -->
<style>
  ion-icon.brand { color: hotpink; }
</style>
<ion-icon name="logo-ionic" class="brand"></ion-icon>
```

--------------------------------

### Importing Icons as ES Modules in Vue 3

Source: https://context7.com/ionic-team/ionicons/llms.txt

In Vue 3, import icons from `ionicons/icons` and use them with the `IonIcon` component. The icon object can be passed to the `:icon` prop, and you can also set `size` and `color` attributes.

```typescript
// Vue 3 example (using defineComponent)
import { IonIcon } from '@ionic/vue';
import { heart, heartOutline } from 'ionicons/icons';

export default {
  components: { IonIcon },
  setup() {
    return { heart, heartOutline };
  },
  template:
    `
    <ion-icon :icon="heart" size="large" />
    <ion-icon :icon="heartOutline" color="danger" />
  `
};

```

--------------------------------

### Accessibility with `aria-label` and `aria-hidden`

Source: https://context7.com/ionic-team/ionicons/llms.txt

Enhance accessibility by using `aria-label` for descriptive icons or `aria-hidden="true"` for purely decorative icons. The `<ion-icon>` component defaults to `role="img"`.

```html
<!-- Descriptive icon — screen reader announces "Favourite" -->
<button>
  <ion-icon name="heart" aria-label="Favourite"></ion-icon>
</button>

<!-- Decorative icon — hidden from assistive technology -->
<ion-icon name="checkmark-circle" aria-hidden="true"></ion-icon>
<span>Payment confirmed</span>
```

--------------------------------

### Set Custom SVG Asset Base URL with `setAssetPath`

Source: https://context7.com/ionic-team/ionicons/llms.txt

Use `setAssetPath` to override the default base URL for fetching SVG files. This is necessary when serving Ionicons SVGs from a custom CDN or a bundled `/public` directory.

```typescript
import { setAssetPath, addIcons } from 'ionicons';
import { heart, add, save } from 'ionicons/icons';

// Serve SVGs from your own CDN or public folder
setAssetPath(`${window.location.origin}/public/svg/`);

// Only register the icons you actually use (optional but tree-shaking-friendly)
addIcons({ heart, add, save });

// Template usage — SVG fetched from "/public/svg/heart.svg"
// <ion-icon name="heart"></ion-icon>
```

--------------------------------

### Ionicons Icon Variants

Source: https://github.com/ionic-team/ionicons/blob/main/readme.md

Ionicons provides 'filled', 'outline', and 'sharp' variants for most icons. Logo icons do not have outline or sharp variants.

```html
<ion-icon name="heart"></ion-icon> <!--filled-->
<ion-icon name="heart-outline"></ion-icon> <!--outline-->
<ion-icon name="heart-sharp"></ion-icon> <!--sharp-->
```

--------------------------------

### Platform-Specific Icons

Source: https://context7.com/ionic-team/ionicons/llms.txt

Specify different icon variants for iOS and Material Design platforms. Useful within Ionic Framework where the mode is set globally.

```html
<!-- Uses heart-outline on iOS, heart-sharp on Material Design -->
<ion-icon ios="heart-outline" md="heart-sharp"></ion-icon>

<!-- Force a specific mode regardless of the document mode -->
<ion-icon name="heart" mode="ios"></ion-icon>
<ion-icon name="heart" mode="md"></ion-icon>
```

--------------------------------

### Ionicons Icon Color

Source: https://github.com/ionic-team/ionicons/blob/main/readme.md

Specify the icon color by applying the 'color' CSS property to the 'ion-icon' component.

```css
ion-icon {
  color: blue;
}
```

--------------------------------

### Enable/Disable SVG Sanitization

Source: https://context7.com/ionic-team/ionicons/llms.txt

By default, Ionicons sanitizes SVGs fetched via HTTP, removing `<script>` elements and `on*` event handlers. Set `sanitize="false"` to disable this for trusted internal SVGs.

```html
<!-- Default: sanitization enabled — scripts and event handlers removed -->
<ion-icon src="https://external.example.com/icon.svg"></ion-icon>

<!-- Opt out for a fully trusted internal SVG -->
<ion-icon src="/internal/safe-icon.svg" sanitize="false"></ion-icon>
```

--------------------------------

### Control `<ion-icon>` RTL Flip Behavior

Source: https://context7.com/ionic-team/ionicons/llms.txt

The `flip-rtl` attribute controls whether directional icons automatically flip in RTL documents. Set to `false` to prevent auto-flipping or `true` to force a flip.

```html
<!-- document dir="rtl" — chevron-forward auto-flips -->
<html dir="rtl">
  <ion-icon name="chevron-forward"></ion-icon>

  <!-- Prevent auto-flip -->
  <ion-icon name="chevron-forward" flip-rtl="false"></ion-icon>

  <!-- Force flip on a non-directional icon -->
  <ion-icon name="star" flip-rtl="true"></ion-icon>
</html>
```

--------------------------------

### Adjust `<ion-icon>` Stroke Width

Source: https://context7.com/ionic-team/ionicons/llms.txt

Control the stroke width of outline icons using the `--ionicon-stroke-width` CSS custom property. The default value is `32px`.

```html
<style>
  .thin  { --ionicon-stroke-width: 16px; }
  .thick { --ionicon-stroke-width: 56px; }
</style>

<ion-icon name="heart-outline" class="thin"></ion-icon>
<ion-icon name="heart-outline"></ion-icon>           <!-- default 32px -->
<ion-icon name="heart-outline" class="thick"></ion-icon>
```

--------------------------------

### Adjust Icon Stroke Width

Source: https://github.com/ionic-team/ionicons/blob/main/readme.md

Set the `--ionicon-stroke-width` CSS custom property on the `ion-icon` component to adjust the stroke width for outline icons. The default is 32px.

```css
ion-icon {
  --ionicon-stroke-width: 16px;
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.