On this page
Icons provide additional context to elements on the page.
- Overview
- Rules and guidance
- Properties
- Styles
- Accessibility
When to use
- As a visual shorthand to help users quickly identify common actions or concepts, for instance a magnifying glass for search
- To provide visual anchors in navigation menus or headers, helping users scan information faster
- To reinforce meaning alongside text labels in system states or feedback, such as success, error, or warning messages
When not to use
- As pure decoration - icons that do not add functional value or clarify meaning create visual noise and distract the user
- For abstract or complex concepts without an obvious visual metaphor - use text instead
- In place of critical labels - unless the icon is a widely-understood standard, do not use an icon without a text label for primary actions
- When a standard icon contradicts its common meaning - this can be confusing, for instance using a trash can icon to mean anything other than delete
- For every concept - using an icon for one thing does not mean you need to use an icon for everything. Overuse reduces the visual impact of icons across the page
Anatomy
- Icon
Basic usage
Edit live code
<> <TooltipTrigger tooltip='arrow-left'> <Icon name='arrow-left'/> </TooltipTrigger> <TooltipTrigger tooltip='caret-down'> <Icon name='caret-down'/> </TooltipTrigger> <TooltipTrigger tooltip='caret-right'> <Icon name='caret-right'/> </TooltipTrigger> <TooltipTrigger tooltip='chevron-double-left'> <Icon name='chevron-double-left'/> </TooltipTrigger> <TooltipTrigger tooltip='chevron-double-right'> <Icon name='chevron-double-right'/> </TooltipTrigger> <TooltipTrigger tooltip='chevron-down'> <Icon name='chevron-down'/> </TooltipTrigger> <TooltipTrigger tooltip='chevron-left'> <Icon name='chevron-left'/> </TooltipTrigger> <TooltipTrigger tooltip='chevron-right'> <Icon name='chevron-right'/> </TooltipTrigger> <TooltipTrigger tooltip='chevron-up'> <Icon name='chevron-up'/> </TooltipTrigger> <TooltipTrigger tooltip='check'> <Icon name='check'/> </TooltipTrigger> <TooltipTrigger tooltip='copy'> <Icon name='copy'/> </TooltipTrigger> <TooltipTrigger tooltip='cross'> <Icon name='cross'/> </TooltipTrigger> <TooltipTrigger tooltip='delete'> <Icon name='delete'/> </TooltipTrigger> <TooltipTrigger tooltip='edit'> <Icon name='edit'/> </TooltipTrigger> <TooltipTrigger tooltip='equals'> <Icon name='equals'/> </TooltipTrigger> <TooltipTrigger tooltip='minus'> <Icon name='minus'/> </TooltipTrigger> <TooltipTrigger tooltip='overflow-menu'> <Icon name='overflow-menu'/> </TooltipTrigger> <TooltipTrigger tooltip='plus'> <Icon name='plus'/> </TooltipTrigger> <TooltipTrigger tooltip='error'> <Icon name='error'/> </TooltipTrigger> <TooltipTrigger tooltip='info'> <Icon name='info'/> </TooltipTrigger> <TooltipTrigger tooltip='success'> <Icon name='success'/> </TooltipTrigger> <TooltipTrigger tooltip='warning'> <Icon name='warning'/> </TooltipTrigger> <TooltipTrigger tooltip='dollar'> <Icon name='dollar'/> </TooltipTrigger> <TooltipTrigger tooltip='euro'> <Icon name='euro'/> </TooltipTrigger> <TooltipTrigger tooltip='pound'> <Icon name='pound'/> </TooltipTrigger> <TooltipTrigger tooltip='yen'> <Icon name='yen'/> </TooltipTrigger> <TooltipTrigger tooltip='calendar'> <Icon name='calendar'/> </TooltipTrigger> <TooltipTrigger tooltip='download'> <Icon name='download'/> </TooltipTrigger> <TooltipTrigger tooltip='upload'> <Icon name='upload'/> </TooltipTrigger> <TooltipTrigger tooltip='file'> <Icon name='file'/> </TooltipTrigger> <TooltipTrigger tooltip='electricity'> <Icon name='electricity'/> </TooltipTrigger> <TooltipTrigger tooltip='gas'> <Icon name='gas'/> </TooltipTrigger> <TooltipTrigger tooltip='link'> <Icon name='link'/> </TooltipTrigger> <TooltipTrigger tooltip='lock'> <Icon name='lock'/> </TooltipTrigger> <TooltipTrigger tooltip='new-window'> <Icon name='new-window'/> </TooltipTrigger> <TooltipTrigger tooltip='search'> <Icon name='search'/> </TooltipTrigger> <TooltipTrigger tooltip='search-empty'> <Icon name='search-empty'/> </TooltipTrigger> <TooltipTrigger tooltip='anytime'> <Icon name='anytime'/> </TooltipTrigger> <TooltipTrigger tooltip='evening-and-weekend'> <Icon name='evening-and-weekend'/> </TooltipTrigger> <TooltipTrigger tooltip='heating'> <Icon name='heating'/> </TooltipTrigger> <TooltipTrigger tooltip='interval'> <Icon name='interval'/> </TooltipTrigger> <TooltipTrigger tooltip='offpeak'> <Icon name='offpeak'/> </TooltipTrigger> <TooltipTrigger tooltip='peak'> <Icon name='peak'/> </TooltipTrigger> <TooltipTrigger tooltip='shoulder'> <Icon name='shoulder'/> </TooltipTrigger> <TooltipTrigger tooltip='solar'> <Icon name='solar'/> </TooltipTrigger> </>
smart is a second name for the interval icon and renders the same glyph, so it isn't shown separately above.
Variants and features
Pairing icons with text
In most cases, icons should be paired with a text label. Do not assume a standalone icon is universally understood - if a label is absent from an icon that is not a widely-accepted standard, users will have to work out what it means.
Edit live code
<P><Icon name="electricity"/> Example</P>
Standalone icons
If an icon must be used without a visible label, for instance in a condensed toolbar:
- Wrap the icon in a tooltip trigger so that a text label is revealed on hover or focus
- Use VisuallyHidden or an aria-label to ensure screen reader users can identify the action
Edit live code
<TooltipTrigger tooltip='Electricity'> <Icon name="electricity"/> </TooltipTrigger>
Sizing and scaling
When icons need to be sized relative to text, use em units rather than fixed pixels. This ensures icons scale proportionally with their parent text element and maintains the visual relationship between icon and typography across different screen sizes and zoom levels.
Edit live code
<Heading3><Icon name="electricity" size="0.8em"/> Example</Heading3>
Custom colours and sizes
Icons inherit the colour and size of their parent by default. Both can be set manually when needed.
size takes a number, treated as pixels, or any CSS length. color sets the SVG color attribute, which icons drawn with currentColor pick up.
Edit live code
<Cluster spaceBetween={4}> <ClusterItem> <TooltipTrigger tooltip='Inherits colour and size'> <Icon name="electricity"/> </TooltipTrigger> </ClusterItem> <ClusterItem> <TooltipTrigger tooltip='Custom colour'> <Icon name="electricity" color="#B95E04"/> </TooltipTrigger> </ClusterItem> <ClusterItem> <TooltipTrigger tooltip='Custom size'> <Icon name="electricity" size={32}/> </TooltipTrigger> </ClusterItem> <ClusterItem> <TooltipTrigger tooltip='Both'> <Icon name="electricity" size="3rem" color="#07883F"/> </TooltipTrigger> </ClusterItem> </Cluster>
Custom icons
You can override existing icons or add new icons by wrapping your app in IconsProvider. Icons passed to it are merged over the built-in set, so a name that already exists is replaced and a new name is added.
Custom icons should be a last resort - over time they can create inconsistency even within the same icon set, where optical size and stroke width may vary.
If you need an icon not available in Nebula:
- Raise the need with the design system team
- Check the KAE application for suitable custom icons that have already been added
- If a new icon is still needed, source an SVG from Figma or Material UI
All custom icons should be on a square canvas and use currentColor as the default fill colour. Spread props on the svg element.
These examples are not live, because IconsProvider wraps an application at its root rather than a single component.
import { IconsProvider } from '@kaluza-platform/nebula';
const Flame = (props: JSX.IntrinsicElements['svg']) => (
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="none" {...props}>
<path fill="currentColor" d="M8 1C5 5 4 6.5 4 9a4 4 0 0 0 8 0c0-2.5-1-4-4-8Z" />
</svg>
);
<IconsProvider icons={{ flame: Flame }}>
{/* Anywhere inside, <Icon name="flame" /> now renders the custom icon */}
<App />
</IconsProvider>;
You can also use an SVG file directly, as long as it is imported as a React component:
import { IconsProvider } from '@kaluza-platform/nebula';
import Flame from './flame.svg';
<IconsProvider icons={{ flame: Flame }}>
<App />
</IconsProvider>;
usage
- Icon must not be used as pure decoration with no functional meaningDecorative icons create visual noise and distract the user without adding value.Copy rule ID for icon.no-decoration
- Icon must not be used as the sole means of communicating meaningIcons must always be accompanied by a text label or programmatic label. Relying on an icon alone excludes users who cannot perceive or interpret it.Copy rule ID for icon.no-sole-means-of-communication
- Icon should be paired with a visible text labelIcons are visual aids, not a replacement for language. Do not assume a standalone icon is universally understood.Copy rule ID for icon.pair-with-label
- Icon should be consistent in size within the same contextMixing icon sizes in a single navigation, toolbar, or list creates visual noise.Copy rule ID for icon.consistent-size-in-context
- Icon should use em units for size when the icon needs to scale with surrounding textem units ensure icons scale proportionally with their parent text element, maintaining visual consistency across different screen sizes and zoom levels.Copy rule ID for icon.em-units-for-scaling
- Custom icon must use currentColor as the fill colourcurrentColor ensures the icon inherits colour from its parent, making it compatible with theming and colour overrides.Copy rule ID for custom-icon.currentcolor-fill
- Icon should not be used for abstract concepts that have no obvious visual metaphorUse text instead. An icon without a clear visual metaphor forces users to guess its meaning.Copy rule ID for icon.no-abstract-concepts
- Icon should not be used as a substitute for a primary action labelException: the icon is a widely understood standard such as a pencil for edit or a trash can for deleteCopy rule ID for icon.no-substitute-for-primary-label
- Icon should not be used in a way that contradicts the icon's common meaningUsing a familiar icon to mean something unexpected. For instance a trash can for anything other than delete. Creates confusion and slows users down.Copy rule ID for icon.no-contradicting-meaning
- Icon should not be used on every concept simply because an icon was used for one conceptOveruse reduces the visual impact of icons across the page and dilutes their ability to draw attention.Copy rule ID for icon.no-overuse
interaction
- Icon will set aria-hidden="true" and focusable="false" on the SVG element automatically. The icon is never announced by screen readers and never receives focusAll meaning must be provided through a visible label or a programmatic label on the parent element.Copy rule ID for icon.will-aria-hidden
- Icon will render nothing when the name prop does not match a known icon. No error is thrownCopy rule ID for icon.will-renders-nothing-unknown
- Icon must be wrapped in a TooltipTrigger when used without a visible label, so a label is available on hover and focusCopy rule ID for icon.tooltip-when-standalone
- Icon must have a descriptive aria-label, title, or VisuallyHidden label when used without a visible labelWithout a programmatic label, screen reader users cannot identify the icon's meaning or purpose.Copy rule ID for icon.accessible-label-when-standalone
Icon
Also accepts all props from SVGAttributes.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
name | IconName | (string & {}) | — | Yes | Name of the icon to render, looked up in the built-in icons plus any added through `IconsProvider`. Renders nothing if no icon has that name. |
size | string | number | '1em' | No | Width and height of the icon. A number is treated as pixels and a string as any CSS length. |
color | string | — | No | Sets the SVG `color` attribute, which icons drawn with `currentColor` pick up as their colour. |
This component has no styles of its own to document.
In brief
Icon is an svg that is hidden from screen readers. It is never announced and never takes focus, so any meaning it carries has to be written as text.
What Nebula provides
- Every Icon renders with aria-hidden="true", so a screen reader skips it.
- The size defaults to 1em, so the icon scales with the text around it.
Accessible design
Pair every icon that carries meaning with a text label
The icon is hidden from screen readers, so the label is the only thing they announce. An icon beside text is decoration; an icon without text is invisible to a screen reader user.
WCAG: 1.1.1 Non-text Content
If you set a custom colour on an icon that carries meaning, check it reaches 3:1 against its background
The color prop sets the colour of the whole icon, and an icon that is hard to see loses its meaning for a low-vision user.
WCAG: 1.4.11 Non-text Contrast
Accessible development
If an icon stands alone, put its name in text next to it with VisuallyHidden
Where there is no room for a visible label, VisuallyHidden gives the screen reader the text the hidden icon cannot.
WCAG: 1.1.1 Non-text Content
Don't name an icon with aria-label or title
Icon sets aria-hidden="true", and a hidden element's name is not announced. Name the control around the icon instead.
WCAG: 4.1.2 Name, Role, Value
Spread the props onto the svg of every custom icon
Icon passes aria-hidden to the icon component through its props, so a custom icon that drops them is no longer hidden from screen readers.
WCAG: 1.1.1 Non-text Content
Accessibility testing status
Reviewed on 9 October 2026 against v17.0.1.
| Test | Status | Tested with |
|---|---|---|
| Default state | Tested | axe-core via the Storybook test runner (CI) |
| Advanced states | Partially tested | axe-core via the Storybook test runner (CI) |
| Keyboard navigation | Manually tested | keyboard (reported by the owner) |
| Screen reader | Partially tested | VoiceOver with Chrome (reported by the owner) |
What these tests and statuses mean
The table records which checks were run on this component on its own. It is not a statement of WCAG conformance, and it does not cover how the component is used.
The tests
- Default state: The component as it first appears, before anything is clicked or changed.
- Advanced states: Every other state and variant: error, open, selected, each size and style, and hovering.
- Keyboard navigation: Whether every function can be reached and used with the keyboard alone, with a visible focus ring.
- Screen reader: Whether a screen reader announces what is on screen correctly: the name, the role and any state.
The statuses
- Tested: Every check in this row passed in an automated run that repeats on every pull request.
- Manually tested: Every check in this row was run once, by a person or with a tool they started, and all of them passed. It is not re-run on every change.
- Partially tested: Some checks in this row were run once and passed; the rest are still to do.
- Issue found: A check in this row failed. The ticket is shown beside the status.
- Not tested: No check in this row has been run yet.
- Not applicable: This row does not apply to the component, for the reason given beside it.