@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 or aria-labelledby 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.