DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/carbon__icon-helpers package

    10.26.0 • Public • Published


    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


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


    npm i @carbon/icon-helpers

    DownloadsWeekly Downloads






    Unpacked Size

    35.2 kB

    Total Files


    Last publish


    • abbeyhrt
    • dcwarwick
    • jdharvey
    • carbon-design-system
    • joshblack
    • carbon-bot
    • tjegan
    • alisonjoseph
    • adavila
    • shinytoyrobots
    • magedhennawy
    • leechase
    • vpicone
    • dakahn
    • jnm2377
    • jeffreychew
    • simonfinney
    • sstrubberg
    • andreancardona
    • tay1orjones