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

    10.23.0 • Public • Published

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

    Install

    npm i @carbon/icon-helpers

    DownloadsWeekly Downloads

    90,724

    Version

    10.23.0

    License

    Apache-2.0

    Unpacked Size

    35.5 kB

    Total Files

    6

    Last publish

    Collaborators

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