or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

Carbon Icons React

Carbon Icons React provides 2,360 React icon components from IBM's Carbon Design System. Each icon is available as an individual, tree-shakeable React component with consistent props, accessibility features, and full TypeScript support.

Package Information

  • Package Name: @carbon/icons-react
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install @carbon/icons-react

Core Imports

import { Add, Edit, Delete, ChevronRight } from "@carbon/icons-react";

For CommonJS:

const { Add, Edit, Delete, ChevronRight } = require("@carbon/icons-react");

Import all icons (not recommended for bundle size):

import * as CarbonIcons from "@carbon/icons-react";

Basic Usage

import { Add, Warning, CheckmarkFilled } from "@carbon/icons-react";

function MyComponent() {
  return (
    <div>
      {/* Basic icon with default 16px size */}
      <Add />
      
      {/* Icon with custom size */}
      <Warning size={24} />
      
      {/* Icon with accessibility label */}
      <CheckmarkFilled aria-label="Success" size={20} />
      
      {/* Icon with custom styling */}
      <Add className="my-icon-style" />
      
      {/* Focusable icon */}
      <Warning aria-label="Warning" tabIndex={0} />
    </div>
  );
}

Architecture

Carbon Icons React is built around several key design patterns:

  • Generated Components: All 2,360 icon components are code-generated from metadata, ensuring consistency
  • Individual Exports: Each icon is exported separately for optimal tree-shaking and bundle size
  • Consistent Interface: All icons share the same CarbonIconProps interface and behavior
  • Accessibility First: Icons are decorative by default but become semantic when accessibility props are provided
  • Size System: Standardized sizing (16px, 20px, 24px, 32px) with 16px default
  • TypeScript Support: Full type definitions with generic props extending React SVG attributes

Capabilities

Icon Components

All 2,360 icon components follow the same interface and behavior patterns. Icons are categorized across various domains including actions, navigation, status, file types, and IBM-specific products.

/**
 * React icon component with Carbon Design System styling and behavior
 * Each icon supports size variants, accessibility features, and custom styling
 */
type CarbonIconType = React.ForwardRefExoticComponent<
  CarbonIconProps & React.RefAttributes<React.ReactSVGElement>
>;

interface CarbonIconProps extends IconProps {
  /** Icon size in pixels. Supports 16, 20, 24, 32. Defaults to 16. */
  size?: number | string;
}

interface IconProps extends Omit<React.SVGProps<React.ReactSVGElement>, 'ref' | 'tabIndex'> {
  /** Makes icon focusable. Use string for legacy support, will be removed in v12 */
  tabIndex?: string | number | undefined;
  /** Title for the SVG element */
  title?: string | undefined;
  /** CSS class name for custom styling */
  className?: string;
  /** Accessibility label - makes icon semantic instead of decorative */
  "aria-label"?: string;
  /** References element that labels this icon */
  "aria-labelledby"?: string;
  /** Controls screen reader visibility. Auto-managed based on aria-label presence */
  "aria-hidden"?: boolean | 'true' | 'false';
  /** Icon width in pixels */
  width?: number | string;
  /** Icon height in pixels */
  height?: number | string;
  /** SVG viewBox attribute */
  viewBox?: string;
  /** SVG preserveAspectRatio attribute */
  preserveAspectRatio?: string;
}

Icon Categories and Examples:

Actions (100+ icons):

  • Add, Edit, Delete, Save, Close, Menu, Search, Filter, Settings
  • Download, Upload, Share, Copy, Cut, Paste

Navigation (50+ icons):

  • ChevronUp, ChevronDown, ChevronLeft, ChevronRight
  • ArrowUp, ArrowDown, ArrowLeft, ArrowRight
  • Home, Back

Status & Alerts (30+ icons):

  • CheckmarkFilled, Checkmark, WarningFilled, Warning
  • ErrorFilled, Error, InformationFilled, Information

Media Controls (20+ icons):

  • Play, PlayFilled, Pause, PauseFilled, Stop, StopFilled
  • VolumeUp, VolumeDown, VolumeMute

File Types (50+ icons):

  • Document, Folder, FolderOpen, Pdf, Image, Video, Code

Technology & Development (100+ icons):

  • Cloud, Database, Server, Api, Code, Terminal

IBM & Watson Products (50+ icons):

  • Watson, WatsonxAssistant, WatsonMachineLearning
  • LogoKubernetes, LogoDocker

Size Variants

All icons support standardized Carbon Design System sizes.

/**
 * Supported icon sizes following Carbon Design System specifications
 */
type IconSize = 16 | 20 | 24 | 32 | string | number;

Usage Examples:

import { Add, Warning } from "@carbon/icons-react";

// Default 16px size
<Add />

// Standard Carbon sizes  
<Add size={16} />  // Small (default)
<Add size={20} />  // Medium-small
<Add size={24} />  // Medium
<Add size={32} />  // Large

// Custom sizes (use sparingly)
<Add size={40} />
<Add size="2rem" />

Accessibility Features

Icons provide comprehensive accessibility support with automatic behavior switching.

/**
 * Accessibility behavior:
 * - Decorative by default (aria-hidden="true")
 * - Semantic when aria-label or aria-labelledby provided
 * - Focusable when tabIndex specified
 */
interface AccessibilityProps {
  /** Makes icon announced by screen readers and adds semantic role */
  "aria-label"?: string;
  /** References element that describes this icon */
  "aria-labelledby"?: string;
  /** Makes icon keyboard focusable */
  tabIndex?: number | string;
}

Usage Examples:

import { Warning, Add } from "@carbon/icons-react";

// Decorative icon (default)
<Warning />  // aria-hidden="true" automatically applied

// Semantic icon
<Warning aria-label="Warning message" />  // role and aria-hidden managed automatically

// Focusable semantic icon
<Add aria-label="Add item" tabIndex={0} />  // Keyboard accessible

// Referenced by external label
<Warning aria-labelledby="warning-text" />
<span id="warning-text">Critical system warning</span>

Styling and Theming

Icons support flexible styling through CSS and Carbon Design System integration.

/**
 * Styling approaches for icon customization
 */
interface StylingProps {
  /** CSS class name for custom styles */
  className?: string;
  /** Inline styles (use className preferred) */
  style?: React.CSSProperties;
}

CSS Styling:

/* Basic icon coloring */
.my-icon {
  fill: #0f62fe; /* IBM Blue 60 */
}

/* Two-tone icon support */
.my-two-tone-icon {
  fill: #f1c21b; /* IBM Yellow 30 */
}

.my-two-tone-icon [data-icon-path="inner-path"] {
  fill: #161616; /* IBM Gray 100 */
  opacity: 1;
}

/* Size customization */
.large-icon {
  width: 48px;
  height: 48px;
}

Usage Examples:

import { WarningFilled, Add } from "@carbon/icons-react";

// CSS class styling
<Add className="my-icon" />

// Inline styling (not recommended)
<WarningFilled style={{ fill: '#da1e28' }} />

// Two-tone icon
<WarningFilled className="my-two-tone-icon" />

Icon Naming Convention

Icons follow a consistent naming pattern for predictable imports.

Source to Component Name Mapping:

  • Source: kebab-case (e.g., "arrow-right", "warning-filled")
  • Import: PascalCase (e.g., "ArrowRight", "WarningFilled")

Variant Suffixes:

  • --filled → Filled (e.g., WarningFilled)
  • --outline → Outline (e.g., PlayOutline)
  • --alt → Alt (e.g., ThreeDCursorAlt)

Usage Examples:

// Basic icons
import { Add, Edit, Delete } from "@carbon/icons-react";

// Filled variants  
import { AddFilled, PlayFilled, CheckmarkFilled } from "@carbon/icons-react";

// Alternative versions
import { ThreeDCursorAlt, DirectLinkAlt } from "@carbon/icons-react";

// Complex names
import { WatsonMachineLearning, LogoKubernetes } from "@carbon/icons-react";

Bundle Optimization

The package is designed for optimal bundle size through individual exports and tree-shaking.

/**
 * Import strategies for bundle optimization
 */

// ✅ Individual imports (recommended) - only imports specific icons
import { Add, Edit, Delete } from "@carbon/icons-react";

// ✅ Named imports (good) - tree-shakeable
import { Add } from "@carbon/icons-react";
import { Edit } from "@carbon/icons-react"; 

// ❌ Namespace import (not recommended) - imports all 2,360 icons
import * as Icons from "@carbon/icons-react";

TypeScript Support

Full TypeScript definitions are provided for all icons and props.

/**
 * Complete TypeScript definitions for Carbon Icons React
 */
import { CarbonIconType, CarbonIconProps } from "@carbon/icons-react";

// Each icon component type
const Add: CarbonIconType;
const Edit: CarbonIconType;
const Delete: CarbonIconType;

// Props interface
interface CarbonIconProps extends React.SVGProps<React.ReactSVGElement> {
  size?: number | string;
  tabIndex?: string | number;
  title?: string;
}

// Forward ref typing
type CarbonIconType = React.ForwardRefExoticComponent<
  CarbonIconProps & React.RefAttributes<React.ReactSVGElement>
>;

Deprecated Icons

Nine icons are marked as deprecated and should be avoided in new development:

/**
 * Deprecated icons - avoid using in new code
 * These icons are still exported for backwards compatibility but have preferred replacements
 */

// Deprecated - use LogoKubernetes instead
const Kubernetes: CarbonIconType; 

// Deprecated - use appropriate ibm-cloud--direct-link variant
const DirectLink: CarbonIconType;

// Deprecated - use DatabaseEnterprisedb instead  
const DatabaseEnterpriseDb2: CarbonIconType;

// Deprecated - use IbmCloudVpc instead
const VirtualPrivateCloudAlt: CarbonIconType;

// Deprecated - use IbmWatsonxAssistant instead
const IbmWatsonAssistant: CarbonIconType;

// Deprecated - use IbmWatsonMachineLearning instead
const WatsonMachineLearning: CarbonIconType;

// Deprecated - use Watsonx instead
const Watson: CarbonIconType;

// Deprecated - use Carbon AILabel component instead
const AI: CarbonIconType;

// Deprecated - use MachineLearningModel instead
const MachineLearning: CarbonIconType;

Migration Guide:

// ❌ Deprecated usage
import { Watson, Kubernetes, AI } from "@carbon/icons-react";

// ✅ Preferred alternatives
import { Watsonx, LogoKubernetes, MachineLearningModel } from "@carbon/icons-react";
// For AI functionality, use Carbon's AILabel component instead

Common Usage Patterns

Interactive Icon Buttons:

import { Add, Edit, Delete } from "@carbon/icons-react";

function IconButton({ icon: Icon, label, onClick, ...props }) {
  return (
    <button onClick={onClick} aria-label={label}>
      <Icon size={16} aria-hidden="true" {...props} />
    </button>
  );
}

// Usage
<IconButton icon={Add} label="Add item" onClick={handleAdd} />
<IconButton icon={Edit} label="Edit item" onClick={handleEdit} />
<IconButton icon={Delete} label="Delete item" onClick={handleDelete} />

Status Indicators:

import { CheckmarkFilled, WarningFilled, ErrorFilled } from "@carbon/icons-react";

function StatusMessage({ type, message }) {
  const icons = {
    success: CheckmarkFilled,
    warning: WarningFilled,
    error: ErrorFilled,
  };
  
  const Icon = icons[type];
  
  return (
    <div className={`status-${type}`}>
      <Icon size={16} aria-label={`${type} status`} />
      <span>{message}</span>
    </div>
  );
}

Navigation Elements:

import { ChevronRight, Home, ArrowLeft } from "@carbon/icons-react";

function Breadcrumb({ items }) {
  return (
    <nav aria-label="Breadcrumb">
      <Home size={16} aria-label="Home" />
      {items.map((item, index) => (
        <React.Fragment key={index}>
          <ChevronRight size={16} aria-hidden="true" />
          <span>{item}</span>
        </React.Fragment>
      ))}
    </nav>
  );
}

Dependencies

Runtime Dependencies:

  • @carbon/icon-helpers: ^10.52.0 - Utility functions for icon attributes and SVG generation
  • prop-types: ^15.7.2 - Runtime prop validation for React components
  • @ibm/telemetry-js: ^1.5.0 - IBM telemetry collection system

Peer Dependencies:

  • react: >=16 (React 16 or higher required)

Development Build Dependencies:

  • @carbon/icon-build-helpers: ^1.30.0 - Code generation utilities for building React components
  • @carbon/icons: ^11.49.0 - Source icon metadata containing all 2,360 icon definitions

IBM Telemetry

This package uses IBM Telemetry to collect anonymous usage metrics. Telemetry data helps IBM understand how Carbon icons are being used to improve the design system.

Collected Data

The telemetry system automatically collects:

  • JSX element usage (icon components used)
  • Allowed attribute usage (size, aria-label, className, etc.)
  • Package dependency information

Opting Out

To disable telemetry collection, set the environment variable:

# Disable telemetry for all IBM packages
export IBM_TELEMETRY_DISABLED=true

# Or disable for specific package
export IBM_TELEMETRY_DISABLED_@carbon/icons-react=true

You can also opt out using npm configuration:

npm config set @ibm/telemetry-config-disabled true

Telemetry Configuration

The package includes a telemetry.yml configuration file that defines:

  • Project ID: e31e2f56-3767-407b-a854-ad7b9cd27677
  • Collection endpoint for metrics
  • Specific attributes and elements tracked

For more information, see IBM Telemetry documentation.

Types

/**
 * Complete type definitions for Carbon Icons React
 */

// Main icon component type
export type CarbonIconType = React.ForwardRefExoticComponent<
  CarbonIconProps & React.RefAttributes<React.ReactSVGElement>
>;

// Props interface for all icon components
export interface CarbonIconProps extends IconProps {
  /** Icon size in pixels. Supports 16, 20, 24, 32. Defaults to 16px. */
  size?: number | string;
}

// Base icon props extending React SVG attributes
export interface IconProps extends Omit<React.SVGProps<React.ReactSVGElement>, 'ref' | 'tabIndex'> {
  /** Makes icon focusable. String support deprecated, use number. */
  tabIndex?: string | number | undefined;
  /** Title attribute for the SVG element */
  title?: string | undefined;
}

// Common icon sizes following Carbon Design System
export type CarbonIconSize = 16 | 20 | 24 | 32;

// Accessibility states
export type AriaHidden = boolean | 'true' | 'false';