Skip Navigation
React Magma

Icon Button

Icon buttons have an icon included in them.

Basic Usage

If children are included with these buttons (usually text), then they render in a style similar to the non-icon buttons. If no children are included, then they render in the icon-only style.

For icon only buttons you must include an aria-label property that accurately describes the function of the button, so that screen-reader users will know the button's purpose.
For icon buttons with text, an aria-label is not needed, as the function of the button should be described in the visible button text.
import React from 'react';
import {
  IconButton,
  ButtonVariant,
  ButtonColor,
  ButtonGroup,
} from 'react-magma-dom';
import {
  PriorityHighIcon,
  CheckIcon,
  NotificationsIcon,
  SettingsIcon,
  AddIcon,
} from 'react-magma-icons';


export function Example() {
  return (
    <>
      <ButtonGroup>
        <IconButton aria-label="Notifications" icon={<NotificationsIcon />} />
        <IconButton
          aria-label="Notifications"
          variant={ButtonVariant.solid}
          icon={<NotificationsIcon />}
        />
        <IconButton
          aria-label="Notifications"
          variant={ButtonVariant.link}
          icon={<NotificationsIcon />}
        />
      </ButtonGroup>
      <br />
      <ButtonGroup>
        <IconButton
          aria-label="Settings"
          color={ButtonColor.secondary}
          icon={<SettingsIcon />}
        />
        <IconButton
          aria-label="Settings"
          color={ButtonColor.secondary}
          variant={ButtonVariant.solid}
          icon={<SettingsIcon />}
        />
        <IconButton
          aria-label="Settings"
          color={ButtonColor.secondary}
          variant={ButtonVariant.link}
          icon={<SettingsIcon />}
        />
      </ButtonGroup>
      <br />
      <ButtonGroup>
        <IconButton
          aria-label="Correct"
          icon={<CheckIcon />}
          color={ButtonColor.subtle}
        />
        <IconButton
          aria-label="Correct"
          color={ButtonColor.subtle}
          variant={ButtonVariant.solid}
          icon={<CheckIcon />}
        />
        <IconButton
          aria-label="Correct"
          color={ButtonColor.subtle}
          variant={ButtonVariant.link}
          icon={<CheckIcon />}
        />
      </ButtonGroup>
      <br />
      <ButtonGroup>
        <IconButton
          aria-label="Error"
          color={ButtonColor.danger}
          icon={<PriorityHighIcon />}
        />
        <IconButton
          aria-label="Error"
          color={ButtonColor.danger}
          variant={ButtonVariant.solid}
          icon={<PriorityHighIcon />}
        />
        <IconButton
          aria-label="Error"
          color={ButtonColor.danger}
          variant={ButtonVariant.link}
          icon={<PriorityHighIcon />}
        />
      </ButtonGroup>
      <br />
      <ButtonGroup>
        <IconButton
          aria-label="Add"
          color={ButtonColor.success}
          icon={<AddIcon />}
        />
        <IconButton
          aria-label="Add"
          color={ButtonColor.success}
          variant={ButtonVariant.solid}
          icon={<AddIcon />}
        />
        <IconButton
          aria-label="Add"
          color={ButtonColor.success}
          variant={ButtonVariant.link}
          icon={<AddIcon />}
        />
      </ButtonGroup>
      <br />
      <ButtonGroup>
        <IconButton
          aria-label="Notifications"
          disabled
          icon={<NotificationsIcon />}
        />
        <IconButton icon={<NotificationsIcon />} aria-label="Notifications">
          Notifications
        </IconButton>
      </ButtonGroup>
      <br />
      <ButtonGroup>
        <IconButton
          aria-label="Settings"
          icon={<SettingsIcon />}
          color={ButtonColor.secondary}
          variant={ButtonVariant.solid}
        >
          Settings
        </IconButton>
        <IconButton
          icon={<CheckIcon />}
          variant={ButtonVariant.link}
          aria-label="Check"
        >
          Submit
        </IconButton>
      </ButtonGroup>
    </>
  );
}

Assign Icon to Variable

If you find JSX being passed in as a prop directly ugly, you can assign an icon to a variable and pass that in as the prop.

import React from 'react';
import { IconButton } from 'react-magma-dom';
import { NotificationsIcon } from 'react-magma-icons';


export function Example() {
  const icon = <NotificationsIcon />;


  return <IconButton aria-label="Notifications" icon={icon} />;
}

Custom Size

Icon buttons have default sizes for small, medium and large icon buttons respectively. However, if a pixel size is specified for an icon itself, that size will take precedence.

import React from 'react';
import { IconButton } from 'react-magma-dom';
import { NotificationsIcon } from 'react-magma-icons';


export function Example() {
  const icon = <NotificationsIcon size={10} />;


  return (
    <IconButton aria-label="Notifications" icon={icon}>
      With Custom Icon Size
    </IconButton>
  );
}

Icon Position

Use the optional prop iconPosition to position the icon of the button on either side of the text. The iconPosition property takes the values left and right.

import React from 'react';
import {
  ButtonColor,
  ButtonIconPosition,
  IconButton,
  ButtonGroup,
} from 'react-magma-dom';
import { NotificationsIcon, InfoIcon } from 'react-magma-icons';


export function Example() {
  return (
    <ButtonGroup>
      <IconButton icon={<NotificationsIcon />} aria-label="Notifications">
        Icon Left
      </IconButton>
      <IconButton
        color={ButtonColor.secondary}
        icon={<InfoIcon />}
        iconPosition={ButtonIconPosition.right}
        aria-label="Information"
      >
        Icon Right
      </IconButton>
    </ButtonGroup>
  );
}

Sizes

Sizes for IconButtons include small, medium, and large, with medium being the default value.

import React from 'react';
import {
  ButtonIconPosition,
  ButtonSize,
  IconButton,
  ButtonGroup,
} from 'react-magma-dom';
import { NotificationsIcon } from 'react-magma-icons';


export function Example() {
  return (
    <>
      <ButtonGroup>
        <IconButton
          icon={<NotificationsIcon />}
          size={ButtonSize.small}
          aria-label="Notifications"
        />
        <IconButton icon={<NotificationsIcon />} aria-label="Notifications" />
        <IconButton
          icon={<NotificationsIcon />}
          aria-label="Notifications"
          size={ButtonSize.large}
        />
      </ButtonGroup>
      <br />
      <ButtonGroup>
        <IconButton
          aria-label="Notifications"
          icon={<NotificationsIcon />}
          size={ButtonSize.small}
          iconPosition={ButtonIconPosition.left}
        >
          Small Notifications
        </IconButton>
        <IconButton
          aria-label="Notifications"
          icon={<NotificationsIcon />}
          iconPosition={ButtonIconPosition.left}
        >
          Medium Notifications
        </IconButton>
        <IconButton
          aria-label="Notifications"
          icon={<NotificationsIcon />}
          size={ButtonSize.large}
          iconPosition={ButtonIconPosition.left}
        >
          Large Notifications
        </IconButton>
      </ButtonGroup>
    </>
  );
}

Shape

Icon only buttons have shape = round, by default.

import React from 'react';
import { ButtonShape, IconButton, ButtonGroup } from 'react-magma-dom';
import { NotificationsIcon } from 'react-magma-icons';


export function Example() {
  return (
    <ButtonGroup>
      <IconButton icon={<NotificationsIcon />} aria-label="Notifications" />
      <IconButton
        icon={<NotificationsIcon />}
        aria-label="Notifications"
        shape={ButtonShape.fill}
      />
      <IconButton
        icon={<NotificationsIcon />}
        aria-label="Notifications"
        shape={ButtonShape.rightCap}
      />
      <IconButton
        icon={<NotificationsIcon />}
        aria-label="Notifications"
        shape={ButtonShape.leftCap}
      />
    </ButtonGroup>
  );
}

Full-Width Buttons

The isFullWidth property will set the button to display full-width. This property does not have any effect on icon-only buttons.

import React from 'react';
import { ButtonIconPosition, IconButton } from 'react-magma-dom';
import { NotificationsIcon } from 'react-magma-icons';


export function Example() {
  return (
    <>
      <IconButton
        icon={<NotificationsIcon />}
        isFullWidth
        aria-label="Notifications"
      >
        Full-Width Notifications Btn
      </IconButton>
      <br />
      <IconButton
        icon={<NotificationsIcon />}
        isFullWidth
        iconPosition={ButtonIconPosition.right}
        aria-label="Notifications"
      >
        Full-Width Notifications Btn
      </IconButton>
      <br />
      <IconButton
        icon={<NotificationsIcon />}
        aria-label="Notifications"
        isFullWidth
      />
    </>
  );
}

Inverse

import React from 'react';
import {
  IconButton,
  ButtonVariant,
  ButtonColor,
  ButtonGroup,
} from 'react-magma-dom';
import {
  PriorityHighIcon,
  NotificationsIcon,
  Card,
  CardBody,
} from 'react-magma-icons';


export function Example() {
  return (
    <Card isInverse>
      <CardBody>
        <ButtonGroup>
          <IconButton
            aria-label="Alert"
            variant={ButtonVariant.solid}
            icon={<PriorityHighIcon />}
            isInverse
          />
          <IconButton
            aria-label="Notifications"
            variant={ButtonVariant.solid}
            icon={<NotificationsIcon />}
            isInverse
          />
        </ButtonGroup>
      </CardBody>
    </Card>
  );
}

Event Handling

The onClick event will fire when the button is clicked, or when the enter or spacebar key is pressed. Events do not fire on disabled buttons.

import React from 'react';
import { IconButton, ButtonGroup } from 'react-magma-dom';
import { NotificationsIcon } from 'react-magma-icons';
export function Example() {
  const [iconButtonCounter, setIconButtonCounter] = React.useState(0);
  const [textIconButtonCounter, setTextIconButtonCounter] = React.useState(0);


  return (
    <>
      <p>
        <strong>Icon Counter: </strong> {iconButtonCounter} |{' '}
        <strong>Text Icon Counter: </strong> {textIconButtonCounter}
      </p>
      <ButtonGroup>
        <IconButton
          icon={<NotificationsIcon />}
          aria-label="Notifications"
          onClick={() => {
            setIconButtonCounter(count => count + 1);
          }}
        >
          Click me
        </IconButton>
        <IconButton
          icon={<NotificationsIcon />}
          aria-label="Notifications"
          textPosition="left"
          onClick={() => {
            setTextIconButtonCounter(count => count + 1);
          }}
        >
          Click me
        </IconButton>
        <IconButton
          disabled
          icon={<NotificationsIcon />}
          aria-label="Notifications"
          onClick={() => {
            setIconButtonCounter(count => count + 1);
          }}
        >
          Click me if you can
        </IconButton>
      </ButtonGroup>
    </>
  );
}

Testing

Passing in the testId prop will add the data-testid attribute to the button element for easier querying in tests.

<IconButton testId="test-id" aria-label="Test">
  <svg
    aria-hidden="true"
    class="icon"
    height="18"
    width="18"
    fill="currentColor"
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 21.17 23.56"
  >
    <path
      d="M21.9,10.31c0-4.8-5.34-6.49-5.34-6.49V2.22h-2v1.6S9.22,5.51,9.22,10.31,7,20.69,5,20.69v1.9h7.38a3.2,3.2,0,0,0,6.39,0h7.39v-1.9c-2,0-4.24-5.59-4.24-10.38Z"
      transform="translate(-4.98 -2.22)"
    ></path>
  </svg>
</IconButton>

Icon Button Props

This component uses forwardRef. The ref is applied to the button element.

All of the standard button attributes can be provided as props and will be applied to the button element that gets rendered.

aria-label

Description

The text the screen reader will announce. Required for icon-only buttons

Type

string

Default

-

children

Description

The content of the component. If no children are provided, the button will render in an icon only style

Type

node

Default

-

color

Description

The color of the button, indicating its function in the UI

Type

enum, one of:
ButtonColor.primary
ButtonColor.secondary
ButtonColor.danger
ButtonColor.marketing

Default

primary

disabled

Description

If true, element is disabled

Type

boolean

Default

false

icon

Required

Description

Icon to display within the component

Type

React Element

Default

-

iconPosition

Description

Position within the button for the icon to appear

Type

enum, one of:
ButtonIconPosition.left
ButtonIconPosition.right

Default

right

isFullWidth

Description

If true, the button will take up the full width of its container

Type

boolean

Default

false

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

shape

Description

Defines the border radius

Type

enum, one of:
ButtonShape.fill
ButtonShape.leftCap
ButtonShape.rightCap
ButtonShape.round

Default

round

size

Description

The relative size of the button

Type

enum, one of:
ButtonSize.large
ButtonSize.medium
ButtonSize.small

Default

medium

textTransform

Description

Determines whether the button appears in all-caps

Type

enum, one of:
ButtonTextTransform.uppercase
ButtonTextTransform.none

Default

uppercase

type

Description

The type attribute of the button

Type

enum, one of:
ButtonType.button
ButtonType.submit
ButtonType.reset

Default

button

variant

Description

The variant of the button

Type

enum, one of:
ButtonVariant.solid
ButtonVariant.link

Default

solid

On this page

Deploys by Netlify