Skip to content

IconButton

Use icon button as an accessible button component with no text and only icon.
  • Beta
  • Not reviewed for accessibility

Use IconButton to render Icon-only buttons without the default button styles.

IconButton will always render with a tooltip unless the tag is :summary. IconButton will always render with a tooltip unless the tag is :summary.

Accessibility

IconButton requires an aria-label, which will provide assistive technologies with an accessible label. The aria-label should describe the action to be invoked rather than the icon itself. For instance, if your IconButton renders a magnifying glass icon and invokes a search action, the aria-label should be "Search" instead of "Magnifying glass". Either aria-label or aria-description will be used for the Tooltip text, depending on which one is present. Either aria-label or aria-description will be used for the Tooltip text, depending on which one is present. Learn more about best functional image practices (WAI Images)

Arguments

NameTypeDefaultDescription
iconStringN/AName of Octicon to use.
wrapper_argumentsHash{}Optional keyword arguments to be passed to the wrapper <div> tag.
schemeSymbol:defaultOne of :danger, :default, or :invisible.
sizeSymbol:mediumOne of :large, :medium, or :small.
tagSymbolN/AOne of :a, :button, or :summary.
typeSymbolN/AOne of :button, :reset, or :submit.
aria-labelStringN/AString that can be read by assistive technology. A label should be short and concise. See the accessibility section for more information.
aria-descriptionStringN/AString that can be read by assistive technology. A description can be longer as it is intended to provide more context and information. See the accessibility section for more information.
show_tooltipBooleantrueWhether or not to show a tooltip when this button is hovered. Tooltips should only be hidden if the aria label is redundant, i.e. if the icon has a widely understood definition.
tooltip_directionSymbol:sOne of :e, :n, :ne, :nw, :s, :se, :sw, or :w.
system_argumentsHashN/ASystem arguments

Examples

Default

Search
<%= render(Primer::Beta::IconButton.new(icon: :search, "aria-label": "Search", id: "search-button", id: "search-button")) %>

Schemes

Search
Delete
<%= render(Primer::Beta::IconButton.new(icon: :search, "aria-label": "Search")) %>
<%= render(Primer::Beta::IconButton.new(icon: :trash, "aria-label": "Delete", scheme: :danger)) %>

With an aria-description

If you need to have a longer description for the icon button, use both the aria-label and aria-description attributes. A label should be short and concise, while the description can be longer as it is intended to provide more context and information. See the accessibility section for more information.

Add bold text, Cmd+b
<%= render(Primer::Beta::IconButton.new(icon: :bold, "aria-label": "Bold", "aria-description": "Add bold text, Cmd+b")) %>

Custom tooltip direction

Search
<%= render(Primer::Beta::IconButton.new(icon: :search, "aria-label": "Search", tooltip_direction: :e)) %>