Icon button

A compact button with an icon and no text.

Props

icon
GoabIconType
Sets the icon.
action
string
Action identifier passed in click events for event delegation patterns.
actionArg
string
Single argument value passed with the action in click events.
actionArgs
Record<string, unknown>
Multiple argument values passed with the action in click events.
ariaLabel
string
Sets the aria-label of the button.
disabled
boolean
Disables the button.
size
GoabIconSize
Sets the size of button.
Defaults to medium.
testId
string
Sets a data-testid attribute for automated testing.
theme
GoabIconTheme
Sets the theme of the icon inside the button. "outline" for stroked icons, "filled" for solid icons.
Defaults to outline.
title
string
Sets the title of the button.
type
GoabIconButtonType
Sets the visual style of the button.
Defaults to default.
variant
GoabIconButtonVariant
Styles the button to show color, light, dark or destructive action.
Defaults to color.
mt, mr, mb, ml
Spacing
Apply margin to the top, right, bottom, and/or left of the component.
icon
GoabIconType
Sets the icon.
action
string
Action identifier passed in click events for event delegation patterns.
actionArg
string
Single argument value passed with the action in click events.
actionArgs
Record<string, unknown>
Multiple argument values passed with the action in click events.
ariaLabel
string
Sets the aria-label of the button.
disabled
boolean
Disables the button.
size
GoabIconSize
Sets the size of button.
Defaults to medium.
testId
string
Sets the data-testid attribute for automated testing.
theme
GoabIconTheme
Sets the icon theme. "outline" for stroked icons, "filled" for solid icons.
Defaults to outline.
title
string
Sets the title of the button.
type
GoabIconButtonType
Sets the visual style of the button.
Defaults to default.
variant
GoabIconButtonVariant
Styles the button to show color, light, dark or destructive action.
mt, mr, mb, ml
Spacing
Apply margin to the top, right, bottom, and/or left of the component.
icon
GoabIconType
Sets the icon.
action
string
Action identifier passed in click events for event delegation patterns.
action-arg
string
Single argument value passed with the action in click events.
action-args
Record<string, unknown>
Multiple argument values passed with the action in click events.
Defaults to {}.
arialabel
string
Sets the aria-label of the button.
disabled
boolean true | false
Disables the button.
Defaults to false.
inverted
boolean true | false
When true, inverts the icon colors for use on dark backgrounds.
Defaults to false.
size
IconSize
Sets the size of button.
Defaults to medium.
testid
string
Sets a data-testid attribute for automated testing.
theme
IconTheme
Sets the icon theme. 'outline' for stroked icons, 'filled' for solid icons.
Defaults to outline.
title
string
Sets the title of the button.
type
GoabIconButtonType default | tertiary
Sets the visual style of the button.
Defaults to default.
variant
GoabIconButtonVariant color | nocolor | light | dark | destructive
Styles the button to show color, light, dark or destructive action.
Defaults to color.
mt, mr, mb, ml
Spacing
Apply margin to the top, right, bottom, and/or left of the component.

Events

onClick
() => void
Callback fired when the icon button is clicked.
onClick
() => void
Emits when the icon button is clicked.
_click
CustomEvent<{ event: Event }>
Examples

Copy to clipboard

Show a label on an icon only button

Show multiple actions in a compact table

States

Submit

Only use disabled buttons if research shows it makes the user interface easier to understand.

Consider removing options that are unavailable or not applicable. Show actions that are only relevant and useful to the user at a given time.

Don't
Avoid using disabled buttons. They have poor contrast and can confuse users.
Submit

When you must disable a button or input:

  • Provide nearby text explaining what needs to happen first
  • Consider showing the element enabled with validation on submit instead
  • Use aria-describedby to link the disabled element to explanatory text
Don't
Don't disable buttons or inputs without explaining why. Disabled controls can be confusing and users may not understand why they can't interact with an element.

Types

Go to homepage
Don't
Don't use Button for simple navigation (use Link), toggling state (use Toggle or Checkbox), or minor utility functions (use Icon Button).

Positioning

SubmitCancel
Do
Use a button group when putting multiple buttons together.

Usage

Don't
Don't use icon buttons for actions that are not easily understood.
Do
Use icon buttons for universal actions such as closing a modal window.

Feedback

Do
Use tooltips to describe an icon button and provide clarity on what the icon button will do.
Don't
Don't use tooltips inconsistently; if one icon button has a tooltip, the rest of the icon buttons must also have tooltips.
All GoA Design System components are built to meet WCAG 2.2 AA standards. The following guidelines provide additional context for accessible implementation.

Screen Readers

Icon-only interactive elements must have an accessible label so screen reader users understand their purpose.

For IconButton: The ariaLabel prop is required.

// Good - describes the action
<GoabIconButton icon="trash" ariaLabel="Delete item" />

// Bad - no label for screen readers
<GoabIconButton icon="trash" />

For Badge with icon only: Provide ariaLabel when there’s no visible text.

<GoabBadge icon="warning" ariaLabel="Warning" type="important" />

For Icon: Use ariaLabel when the icon conveys meaning, not just decoration.

The label should describe:

  • What action happens (for buttons): “Delete”, “Edit”, “Close”
  • What the icon represents (for informational icons): “Warning”, “Success”

For decorative icons: Set ariaHidden to true when nearby text or the parent control already communicates the same meaning. This prevents screen readers from announcing duplicate information.

<GoabIcon type="checkmark-circle" ariaHidden />
<span>Application saved</span>

Do not use ariaHidden to replace a missing accessible label. If the icon provides information that is not available elsewhere, use ariaLabel instead.

Don't
Don't use icon-only elements without an accessible label
Do
Icon-only buttons must include a descriptive label for screen readers.

Focus

Don't
Don't focus on just the icon within a button. Focus the button as a whole.

Accessibility

Do
Use a tooltip to clearly indicate an icon button's function when there's no visible label.

Related components

Button

Carry out an important action or navigate to another page.
Icons

A simple and universal graphic symbol representing an action, object, or concept to help guide the user.
View old component docs