carbon-icons-svelte

You can use the optimizeImports preprocessor from carbon-preprocess-svelte to allow using concise barrel file import syntax while maintaining fast development times. The preprocessor automatically rewrites imports to the specific file path.

Example transformation:

- import { Add } from "carbon-icons-svelte";
+ import Add from "carbon-icons-svelte/lib/Add.svelte";

Install the library using your preferred package manager:

# npm
npm i carbon-icons-svelte

# pnpm
pnpm i carbon-icons-svelte

# Yarn
yarn add carbon-icons-svelte

# Bun
bun add carbon-icons-svelte

To avoid slow development times caused by the large library size, import icons directly from the carbon-icons-svelte/lib folder instead of using the barrel file.

Refer to the Icon Index for the full list of available icon names.

<script>
  import Add from "carbon-icons-svelte/lib/Add.svelte";
</script>

<Add />

Use the size prop to specify the icon size in pixels. While the Carbon Design System standard scale is 16, 20, 24, and 32, you can pass any number.

<Add size={16} />
<Add size={20} />
<Add size={24} />
<Add size={32} />

The library provides TypeScript support for Svelte 4 and Svelte 5. You can import the CarbonIconProps type to type your icon property objects.

<script lang="ts">
  import Add from "carbon-icons-svelte/lib/Add.svelte";
  import type { CarbonIconProps } from "carbon-icons-svelte";

  const props: CarbonIconProps = {
    size: 16,
    fill: "red",
    "data-test": "id",
  };
</script>

<Add {...props} />

All props are optional. The component forwards $$restProps to the underlying svg element, allowing you to use attributes like fill, class, or any valid SVG attribute.

Props

Common Usage Patterns

Customizing color and classes:

<Add fill="red" class="icon" />

Accessibility (Labelled):

<Add aria-label="Add" />

Accessibility (Labelled by):

<label id="add-file">Add file</label>
<Add aria-labelledby="add-file" />

Focusable icons:

<Add aria-label="Add" tabindex={0} />

The buildIcons function is an asynchronous utility used to generate the icon library files (Svelte components, TypeScript definitions, and index files) from the @carbon/icons metadata. It handles icon deprecations, renames (aliases), and generates the ICON_INDEX.md and build information files.

import { buildIcons } from "@carbon/icons-svelte";

const iconNames = await buildIcons();
console.log("Generated icons:", iconNames);

When working with icons from this library, you can use the CarbonIconProps type to define the expected properties for an icon component. This type extends standard Svelte SVG HTML elements and includes specific Carbon icon properties.

import type { CarbonIconProps } from "@carbon/icons-svelte";

// CarbonIconProps includes:
// - title?: string (The icon title, defaults to undefined)
// - size?: 16 | 20 | 24 | 32 | (number & {}) (The icon size, defaults to 16)
// - All standard SvelteHTMLElements["svg"] attributes