@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 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.