Icons
KinetixUI provides the layout and a sensible default. Your application can provide the icon.
KinetixUI does not ship its own icon set, and it does not translate icon names between platforms. Each platform draws its components' icons from the icon system developers on that platform already use. Where a component has an icon a product team would reasonably want to change, it offers a slot for it, and the component keeps owning everything around the icon: its size, its colour in every state, its accessible name and which way it points in a right-to-left layout.
At a glance#
| Platform | Default source | Your own icon | Extra package |
|---|---|---|---|
| React | lucide-react | any ReactNode (Lucide, Heroicons, Phosphor, an inline SVG, your icon component) | none: lucide-react is already a dependency of @kinetixui/ui |
| Angular | inline SVG drawn by the component | content projection: any element carrying the slot's attribute, such as kxDismissIcon | none |
| SwiftUI | SF Symbols | a @ViewBuilder closure: an SF Symbol, an asset Image, any View | none |
| Jetpack Compose | Material icons, drawn by KinetixUI from Material's own vector paths | a @Composable () -> Unit slot: Material Icons, a vector asset, any composable | none: no material-icons artifact is needed |
| Flutter | Material Icons | a Widget? parameter: Material or Cupertino icons, an SVG widget, any widget | none (the Material icon font comes with uses-material-design: true, the flutter create default) |
So, briefly: there is no universal KinetixUI icon set; your platform's familiar icons are the default; your company's icon library works wherever a component has a slot; and nothing extra needs installing.
Why not one icon set everywhere#
- Familiarity. An iOS user expects SF Symbols and an Android user expects Material's shapes. The same close button drawn identically on every platform would look foreign on most of them.
- Ecosystems. Each of these sources is maintained, licensed for use and already in your toolchain.
- Maintenance. A shared set, or a table mapping
"search"to five libraries' names, is a contract that has to be kept true forever, for libraries whose names, variants and meanings do not line up. - Your product. Teams bring their own icons. A slot that takes any icon serves them better than a name KinetixUI has to know about.
Icons mean the same thing on every platform; they are not required to look the same. A close button closes
whether it shows Lucide's X, the xmark symbol or Material's Close.
Replacing a component's icon#
Banner and Inform take a replacement for their dismiss mark on every platform. The example below is
the same on each: the default, a different icon from the platform's usual source, and an icon of your own.
Each snippet is compiled and tested by that platform's CI.
{/* Default: lucide's X */}
<Banner onDismiss={onDismiss}>Changes saved.</Banner>
{/* Another lucide icon */}
<Banner onDismiss={onDismiss} dismissIcon={<CircleX />}>
Changes saved.
</Banner>
{/* Your own icon: sized to 14px, coloured by the banner, named "Dismiss" */}
<Banner onDismiss={onDismiss} dismissIcon={<CompanyCloseIcon />}>
Changes saved.
</Banner>What the component does with whatever you pass:
- Size. It lays your icon out in the slot's box: 14 px (pt, dp) for a dismiss mark. You do not size it.
- Colour. Your icon inherits the component's colour:
currentColoron the web, the foreground style on SwiftUI,LocalContentColoron Compose,IconThemeon Flutter. Draw with those rather than a fixed colour and it follows the theme, dark mode and the disabled state. - Name. The button stays named "Dismiss". Your icon is decorative inside it, so it needs no label of
its own (on Compose, pass
contentDescription = null). - Removal. Leaving the slot out gives you the default. The control itself only exists when you handle
the action (
onDismiss, ordismissibleon Angular), so there is no way to show a dismiss button with no icon in it.
Other icons a component draws, such as a dialog's close button, an accordion's chevron or a checkbox's mark,
are part of the component and not replaceable today. Icons you pass into a component (an icon inside a
Button, a Metric's icon, a TreeItem's icon) were always yours to choose.
Each component's own API table lists its icon props. On React the prop is dismissIcon; on Angular the
kxDismissIcon projection slot; on SwiftUI a trailing dismissIcon: view builder; on Compose and Flutter a
dismissIcon parameter. Angular's CodeBlock also takes a kxCopyIcon.
Icons the components draw#
| Role | React | Angular | SwiftUI | Compose | Flutter | In RTL |
|---|---|---|---|---|---|---|
| Close, dismiss | X | SVG | xmark | Close | Icons.close | does not mirror |
| Back, previous | ChevronLeft | ‹ | chevron.backward | ChevronStart | Icons.chevron_left | mirrors |
| Next, breadcrumb separator | ChevronRight | › | chevron.forward | ChevronEnd | Icons.chevron_right | mirrors |
| Collapsed disclosure (tree, JSON) | ChevronRight | n/a | chevron.forward | text glyph (debt) | Icons.chevron_right | mirrors |
| Expanded disclosure, accordion, select | ChevronDown | SVG | chevron.down | ExpandMore | Icons.keyboard_arrow_down | does not mirror |
| Checked | Check | SVG | checkmark | Check | Icons.check | does not mirror |
| Indeterminate, decrease | Minus | SVG | minus | Remove | Icons.remove | does not mirror |
| Media transport | SkipBack, Rewind, … | n/a | backward.end.fill, … | SkipPrevious, … | Icons.skip_previous, … | does not mirror |
The full, per-component record is icons/mapping.json.
pnpm check:icons fails CI if a recorded icon disappears from its source, if a directional icon stops using
its platform's direction-aware variant, or if a new Unicode character is used as an icon on Compose.
Icon-only controls#
A button with only an icon in it still needs a name: the name of the action, not of the picture. "Delete draft", not "trash can".
<Tooltip>
<TooltipTrigger asChild>
{/* size="icon" keeps the svg visible and turns the text into the button's
screen-reader-only name: "Delete draft, button" */}
<Button size="icon" variant="Ghost" onClick={onDelete}>
<Trash2 />
<span>Delete draft</span>
</Button>
</TooltipTrigger>
<TooltipContent>Delete draft</TooltipContent>
</Tooltip>- React.
Buttonwithsize="icon"keeps its SVG visible and makes any other child screen-reader only, so the text inside it is the name. Lucide icons are hidden from assistive technology automatically. - SwiftUI
.accessibilityLabel("Delete draft"); ComposeModifier.semantics { contentDescription = "Delete draft" }on the clickable, withcontentDescription = nullon theIcon; FlutterIconButton(tooltip: 'Delete draft', …)orSemantics(label:, button: true). - Add a tooltip with the same words when the icon could be read more than one way. A tooltip is a hint for sighted pointer users, not a replacement for the name.
- Keep the whole control a comfortable target, not just the icon:
size="icon"pads an 18 px icon to a 42 px square. Focus shows on the control, like any other button. - If the meaning is not obvious from the icon, show the text. An icon-only control is a space saving, not a goal.
Icons in RTL interfaces#
An icon mirrors when it points along the reading direction, and keeps its shape when it does not.
- Mirrors: back, previous and next, breadcrumb separators, a collapsed disclosure chevron. KinetixUI
handles these on every platform: React flips them with
rtl:-scale-x-100, SwiftUI useschevron.backwardandchevron.forward, Compose uses auto-mirrored vectors, Flutter's chevrons followDirectionality, and Angular's‹and›are characters the browser mirrors itself. - Does not mirror: close, check, minus, an accordion's down chevron, an expanded disclosure (it points down in both directions), and media controls, which name a direction in time rather than on the page.
- Your own icons. An icon you pass into a slot is drawn as you give it. If it is directional, use the
direction-aware form of your icon set: SF Symbols'
.backwardand.forwardnames, an auto-mirrored vector on Compose,matchTextDirectionon a FlutterIcon, or thertl:variant on the web.
The RTL switch on this site's component previews currently changes the direction of the whole page, not just the preview. That is a known issue with the preview, not with the components, and it is being fixed separately. To check your own screens, set the direction on your app's root (see RTL).
Don't#
- Don't use a text character as a UI icon. Its shape depends on the device font, some render as colour emoji that ignore your theme, and screen readers read them out ("multiplication sign").
- Don't put your own SVG next to a component's icon when the component has a slot for it. Use the slot, so the size, colour and name stay right.
- Don't label a decorative icon. Inside a named button, or next to text that says the same thing, the icon adds nothing to what a screen reader should hear.
- Don't colour a slotted icon by hand. A fixed colour stays the same when the component is disabled or the theme changes. Draw with the inherited colour.
- Don't mirror every icon in RTL. Only the ones that point along the reading direction.
- Don't assume an icon name exists everywhere.
X,xmark,CloseandIcons.closeare four different libraries. Pick from your platform's source.
Related#
- Theming: the colour roles icons inherit.
- RTL: setting the direction your icons follow.
- Accessibility: the conventions icon-only controls follow.
- Banner and Inform: the dismiss icon slot.