Icon

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

npmjs.com/package/@telus-uds/ds-allium

Package version

1.14.0

Loading...

<Icon icon={Award} />

<Icon icon={Award} />

Introduction

import { Icon } from '@telus-uds/ds-allium'

A wrapper for svg icons. Takes an icon from the Allium palette, and renders it with theming applied.

Guidance

Design guidance on the usage and choice of Iconography is given in the Icons palette documentation for each category of icons used in the Allium brand.

Accessibility

• Pass an accessibilityLabel for icons that have a meaning that should be communicated to the user. This will be used by assistive technology such as screen readers.
• Don't repeat content in an accessibilityLabel that is already present in text. If an icon's accessibilityLabel would simply repeat the text next to it, it is better to treat the icon as decorative.
• If the accessibilityLabel prop is not passed, the icon will treated as purely decorative and will be set as ignorable by assistive technology via the attribute aria-hidden.
• If an icon is to be included alongside text and has a meaning related to the text, pass the prop scalesWithText as true so that if a sighted users increases their device's text size, the icon also scales to a size similar to the size they find comfortable for reading.

Platform considerations

In web-only projects, use the web palette build to import icons.

import { Users } from '@telus-uds/palette-allium/build/web/icons'
import { Icon } from '@telus-uds/ds-allium'

const icon = <Icon icon={Users} accessibilityLabel="Works on Web" />

In native apps and cross-platform projects, import the palette icons from the rn build instead of the web build. This will select an svg icon for web, and a native svg icon for native platforms.

info

In order for this to work on native platforms, you will need to have react-native-svg installed as a dependency in your project.

import { Users } from '@telus-uds/palette-allium/build/rn/icons'
import { Icon } from '@telus-uds/components-base'

const icon = <Icon icon={Users} accessibilityLabel="Works on Web, iOS and Android" />

Props

Name	Type	Default	Description
accessibilityLabel	string		Descriptive label used in web SVG title tag for accessibility
icon*	elementType		A valid UDS icon component imported from a UDS palette (e.g.) 'import { MyIcon } from @telus-uds/palette-<brand>/build/web/icons'
scalesWithText	bool	false	controls whether the icon size should be proportionate to any accessibility-related font scaling.
tokens	custom		System tokens prop, see tokens for more details
variant	objectOf		System variant prop, see variants for more details

Tokens

In exceptional circumstances, the following tokens can be passed to this component to override its default styles. Do not do this unless absolutely necessary. Read more about overriding styles.

View Tokens

Prop Name	Token Property	Token Type
tokens	size	size
	color	color
	scale	integer
	translateX	size
	translateY	size

Figma

Variants

Icon has a fixed size and colour and does not automatically inherit sizes or colour from surrounding text. Instead, components that use icons alongside text, such as Link, set the icon's size and colour tokens explicitly, to complement the styles of each variant.

There are two variants generally available for icons used outside of such components:

• To change the size of an icon by setting the size variant to one of the following values: micro, small, large, extraLarge (with "normal" size being the default)
• To give an icon a more eye-catching purple colour, set variant { rank: 'primary' }

Loading...

<StackView tokens={{ justifyContent: 'space-around' }} space={2} direction="row"> <Icon icon={Award} variant={{ size: 'micro' }} /> <Icon icon={Award} variant={{ size: 'small', rank: 'primary' }} /> <Icon icon={Award} /> <Icon icon={Award} variant={{ size: 'large', rank: 'primary' }} /> <Icon icon={Award} variant={{ size: 'extraLarge' }} /> </StackView>

<StackView tokens={{ justifyContent: 'space-around' }} space={2} direction="row">
  <Icon icon={Award} variant={{ size: 'micro' }} />
  <Icon icon={Award} variant={{ size: 'small', rank: 'primary' }} />
  <Icon icon={Award} />
  <Icon icon={Award} variant={{ size: 'large', rank: 'primary' }} />
  <Icon icon={Award} variant={{ size: 'extraLarge' }} />
</StackView>

Consult with the Allium brand team if you wish to use other icon styles for a custom component. It is technically possible via the tokens prop but the brand team should be consulted to ensure the desired design is not off-brand or inconsistent.

Feedback

• Spotted a problem with this component? Raise an issue on GitHub
• See any existing issues for this component
• Contact the team on slack in #ds-allium-support