All components
Actions
Utility buttons
stable
Since 1.1
Icon-only actions and dismiss controls: IconButton with variant, tone, size, and loading, plus regular and inverse CloseButton.
Actions
primitive
Display
Documented
import { IconButton } from '@ivim/native/components';
When to use
Use when
An action is recognisable from its icon alone and space is tight — toolbars, table rows, card corners.
You need a dismiss affordance for a dialog, banner, or sheet.
Don't use when
The action is the primary one on the surface — a labelled Button states the outcome plainly.
The icon is ambiguous and needs a visible label to be understood.
Playground
Adjust the controls to preview live prop combinations. The code snippet updates to match the current selection.
variant
variant
primary
secondary
tertiary
tone
tone
brand
gray
destructive
size
size
xs
sm
md
lg
shape
shape
circle
square
Loading
isLoading
Disabled
isDisabled
<IconButton />
Example
Preview
Code
IconButton variants
Primary
Secondary
Tertiary
Destructive
Square shape
IconButton sizes and states
Sizes (xs, sm, md, lg)
Loading
Disabled
With a tooltip (composed, not built in)
CloseButton
Default
Specific accessible name
Sizes (sm, md, lg)
Inverse, over a dark surface
Disabled
Anatomy
The parts that compose this component.
1
Container
Square or circular pressable sized by the size prop, carrying the variant fill.
2
Icon
Children — an SVG icon component, or a text glyph rendered in a themed Text.
3
Spinner
Overlays the icon while loading, preserving the control size.
Guidelines
Do
Write label as the action, not the icon ("Add member", not "Plus").
Do
Wrap in Tooltip when the icon is not self-evident — the tooltip is a visual aid, label remains the accessible name.
Do
Use isInverse on CloseButton over dark or image surfaces so contrast comes from a token, not a hard-coded white.
Don't
Use an icon button for a destructive action without a tooltip or confirmation — the icon alone rarely conveys severity.
Props
Public props for this component. Required props are marked; defaults reflect the component implementation.
label
required
string
Accessible name. Required — an icon-only control has no other name.
variant
'primary' | 'secondary' | 'tertiary'
default: 'tertiary'
Emphasis. There is no link variant for icon-only actions.
tone
'brand' | 'gray' | 'destructive'
default: 'gray'
Semantic intent, shared with Button.
size
'xs' | 'sm' | 'md' | 'lg'
default: 'md'
Control box size. xs and sm add hitSlop to reach the 44px touch target.
shape
'circle' | 'square'
default: 'circle'
Circular, or square with a small radius.
isLoading
boolean
default: false
Overlays a spinner, reports busy, and blocks activation.
isDisabled
boolean
default: false
Dims the control and blocks activation.
isInverse
boolean
default: false
CloseButton only. Foreground for dark or image surfaces, from a semantic token.
Accessibility
Roles and screen-reader behavior this component provides, plus keyboard interactions.
•
IconButton requires label as a prop rather than accepting it optionally, so an unnamed icon button cannot be constructed.
•
CloseButton defaults its accessible name to "Close" and stays overridable for a more specific one ("Close settings").
•
Sizes below the 44px touch target extend their press area with hitSlop instead of shrinking the target (xs adds 8, sm adds 4).
•
Loading reports busy and blocks activation so a second press cannot fire.
•
The inverse close treatment uses a semantic foreground token, so it is not conveyed by a hard-coded color.
Tab
Moves focus to the control.
Space / Enter
Activates it.
Escape
Not handled here — the owning overlay is responsible for Escape-to-dismiss.
Platform & RTL
Behavior that differs across the platforms this component runs on.
Web
Focusable with a visible inset focus ring matched to the circular or square radius.
iOS
Press scale and opacity feedback from PressableFeedback.
Android
Adds a ripple tuned to the border-muted token.
RTL
Icon orientation is the caller’s responsibility; directional icons should be mirrored by the caller.
State coverage
Interaction and visual states this component supports.
base
semantic color
density
Token references
Semantic design tokens this component page exercises. Tap one to edit it live.
Related components
Components that solve adjacent problems or compose with this one.
Button
Action control with four emphasis variants, three semantic tones, five sizes, icon slots, loading, and navigational semantics.
ButtonGroup
Joined group of adjacent segments: an action group, or a single- or multiple-selection control with group and per-item disabled states.
Tooltip
Contextual hint with a required title, an optional secondary description, aligned placements, an arrow, and hover delay — shown on hover and focus on web, long press on native.
PressableFeedback
Pressable wrapper with opacity and scale feedback.