IconButton API

Import

import { IconButton } from "@stratakit/bricks";
// OR
import IconButton from "@stratakit/bricks/IconButton";

IconButton

Base element: <button>

An icon-only button, with a required accessible name.

The icon can be a URL from the @stratakit/icons package:

<IconButton
  label="Reveal full content"
  icon={new URL("@stratakit/icons/arrow.svg", import.meta.url).href}
/>

Alternatively, pass a JSX node such as an <Icon>.

<IconButton
  label={…}
  icon={<Icon href={…} />}
  variant="ghost"
/>

The active prop can be used to turn this button into a toggle button.

const [active, setActive] = React.useState(false);

<IconButton
  label={…}
  icon={…}
  active={active}
  onClick={() => setActive(!active)}
/>

icon

Type: string | Element (required)

Icon to be displayed inside the button.

Can be a URL of an SVG from the @stratakit/icons package, or a custom JSX icon.

label

Type: string (required)

Accessible name for the button.

This label gets used by assistive technology to identify the button, and also gets shown in a tooltip by default.

accessibleWhenDisabled

Type: boolean | undefined (optional)

Indicates whether the element should be focusable even when it is disabled.

This is important when discoverability is a concern. For example:

A toolbar in an editor contains a set of special smart paste functions that are disabled when the clipboard is empty or when the function is not applicable to the current content of the clipboard. It could be helpful to keep the disabled buttons focusable if the ability to discover their functionality is primarily via their presence on the toolbar.

Learn more on Focusability of disabled controls.

active

Type: boolean | undefined (optional)

Default: undefined

Whether the button is in a toggled state and currently “active” (toggled on).

For regular buttons, setting this prop to true or false will turn this button into a toggle button. The button will have an aria-pressed attribute and extra styling for the “active” state. When this prop is undefined, the button will be a regular button (no aria-pressed attribute).

When the button is rendered as an anchor (<a>), this prop maps to aria-current instead of aria-pressed.

autoFocus

Type: boolean | undefined (optional)

Default: false

Automatically focuses the element upon mounting, similar to the native autoFocus prop. This addresses an issue where the element with the native autoFocus attribute might receive focus before React effects are executed.

The autoFocus prop can also be used with Focusable elements within a Dialog component, establishing the initial focus as the dialog opens.

Note: For this prop to work, the focusable prop must be set to true, if it’s not set by default.

disabled

Type: boolean | undefined (optional)

Default: false

Determines if the element is disabled. This sets the aria-disabled attribute accordingly, enabling support for all elements, including those that don’t support the native disabled attribute.

This feature can be combined with the accessibleWhenDisabled prop to make disabled elements still accessible via keyboard.

Note: For this prop to work, the focusable prop must be set to true, if it’s not set by default.

dot

Type: string | undefined (optional)

A small dot displayed in the corner of the icon.

The value of this prop gets used as the button’s “accessible description”.

Example:

<IconButton
  label="Messages"
  dot="You have unread messages"
  icon={…}
/>

key

Type: Key | null | undefined (optional)

labelVariant

Type: "tooltip" | "visually-hidden" | undefined (optional)

Default: "tooltip"

Behavior of the label.

By default, the label is shown in a tooltip. Use "visually-hidden" to hide the label from sighted users.

ref

Type: Ref<HTMLElement | HTMLButtonElement> | undefined (optional)

Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).

render

Type: (props: P) => React.ReactNode | React.ReactElement | undefined (optional)

Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.

Check out the Composition guide for more details.

variant

Type: "solid" | "outline" | "ghost" | undefined (optional)

Default: "solid"

The variant of the button, i.e. solid, outline, or ghost.