Skip to main content
On this page

Icon

Icons provide additional context to elements on the page.

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​

  1. Icon

Basic usage​

Loading...
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='new-window'>
    <Icon name='new-window'/>
  </TooltipTrigger>
  <TooltipTrigger tooltip='search-empty'>
    <Icon name='search-empty'/>
  </TooltipTrigger>
</>

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.

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

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

Loading...
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:

  1. Raise the need with the design system team
  2. Check the KAE application for suitable custom icons that have already been added
  3. 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>;