@carbon/icon-helpers

What is @carbon/icon-helpers?

@carbon/icon-helpers is a utility library for working with Carbon Design System icons. It provides a set of helper functions to manipulate and manage SVG icons, making it easier to integrate and customize icons within your projects.

What are @carbon/icon-helpers's main functionalities?

getAttributes

The `getAttributes` function generates a set of attributes for an SVG element based on the provided options. This is useful for ensuring that your SVG icons have the correct attributes for rendering.

const { getAttributes } = require('@carbon/icon-helpers');
const attributes = getAttributes({
  width: '32',
  height: '32',
  viewBox: '0 0 32 32',
  fill: 'currentColor'
});
console.log(attributes);

toString

The `toString` function converts an SVG element configuration into a string representation. This is useful for rendering SVG icons as strings, which can then be inserted into the DOM or used in other contexts.

const { toString } = require('@carbon/icon-helpers');
const svgString = toString({
  elem: 'svg',
  attrs: {
    width: '32',
    height: '32',
    viewBox: '0 0 32 32',
    fill: 'currentColor'
  },
  content: [{
    elem: 'path',
    attrs: {
      d: 'M16 2L2 30h28L16 2z'
    }
  }]
});
console.log(svgString);

formatAttributes

The `formatAttributes` function formats an object of attributes into a string that can be used directly in an HTML tag. This is useful for dynamically generating SVG elements with the correct attributes.

const { formatAttributes } = require('@carbon/icon-helpers');
const formattedAttributes = formatAttributes({
  width: '32',
  height: '32',
  viewBox: '0 0 32 32',
  fill: 'currentColor'
});
console.log(formattedAttributes);

Other packages similar to @carbon/icon-helpers

svg-sprite

svg-sprite is a powerful tool for creating SVG sprites. It allows you to combine multiple SVG files into a single sprite, which can then be used to efficiently manage and display icons. Compared to @carbon/icon-helpers, svg-sprite focuses more on sprite generation and management rather than individual icon manipulation.

svgo

SVGO is a tool for optimizing SVG files. It removes unnecessary data and reduces the file size of SVGs without affecting their appearance. While @carbon/icon-helpers provides utilities for working with SVG icons, SVGO focuses on optimizing and cleaning up SVG files for better performance.

react-icons

react-icons is a library that provides a collection of popular icon sets as React components. It allows you to easily include icons in your React projects. Unlike @carbon/icon-helpers, which provides utilities for managing SVG attributes and rendering, react-icons offers pre-built icon components for use in React applications.

README

@carbon/icon-helpers

Helpers used alongside icons for digital and software products using the Carbon Design System

Getting started

To install @carbon/icon-helpers in your project, you will need to run the following command using npm:

npm install -S @carbon/icon-helpers

If you prefer Yarn, use the following command instead:

yarn add @carbon/icon-helpers

Usage

@carbon/icon-helpers provides a couple of helpers for rendering <svg> nodes in a document, or to help get the correct attributes to set on an <svg> node. These include:

Name	Type	Description
getAttributes	(attributes: Object) => Object	Get the attributes for an <svg> node
formatAttributes	(attributes: Object) => String	Format the attributes into a string that can be applied to a node in the DOM
toString	(descriptor: Object) => String	Format the given icon descriptor into a string. Useful for templates
toSVG	(descriptor: Object) => DOMNode	Format the given icon descriptor into a DOM node

For most of the methods, attributes corresponds with whatever the name and value would be if you were writing the HTML for the <svg>. For example, if we wanted to set width and height we would do the following:

const { getAttributes } = require('@carbon/icon-helpers');
const attributes = getAttributes({ width: 20, height: 20 });

In order for the icon to be considered focusable, you will need to provide either aria-label, aria-labelledby, or title in the given attributes in addition to tabindex. For example:

const { getAttributes } = require('@carbon/icon-helpers');
const attributes = getAttributes({
  'aria-label': 'My icon label',
  tabindex: '0',
});

Icon descriptors

An icon descriptor is the term we use to describe icon objects exported by @carbon/icons. By default, they will have the following shape:

{
  elem: 'svg',
  attrs: {
    xmlns: 'http://www.w3.org/2000/svg',
    viewBox: '0 0 16 16',
    width: 16,
    height: 16,
  },
  content: [
    {
      elem: 'path',
      attrs: {
        d: '...',
      },
    },
  ],
  name: 'IconName',
  size: 16,
}

You can import these definitions directly from @carbon/icons and use them alongside toSVG or toString by doing:

import { IconName } from '@carbon/icons';
import { toString, toSVG } from '@carbon/icon-helpers';

const iconString = toString(IconName);
const iconSVG = toSVG({
  ...IconName,
  attrs: {
    ...IconName.attrs,
    myCustomAttribute: 'myCustomAttributeValue',
  },
});

🙌 Contributing

We're always looking for contributors to help us fix bugs, build new features, or help us improve the project documentation. If you're interested, definitely check out our Contributing Guide! 👀

📝 License

Licensed under the Apache 2.0 License.

IBM Telemetry

This package uses IBM Telemetry to collect de-identified and anonymized metrics data. By installing this package as a dependency you are agreeing to telemetry collection. To opt out, see Opting out of IBM Telemetry data collection. For more information on the data being collected, please see the IBM Telemetry documentation.