Component API

Icon Button

Basic Usage

Icon buttons have an icon included in them. 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 } from 'react-magma-dom';
import {
  AlertIcon,
  CheckIcon,
  InfoIcon,
  NotificationsIcon,
  SettingsIcon,
} from 'react-magma-icons';

export function Example() {
  return (
    <>
      <p>
        <IconButton aria-label="Notifications" icon={<NotificationsIcon />} />
        <IconButton aria-label="Notifications" icon={<NotificationsIcon />} />
        <IconButton
          aria-label="Notifications"
          variant={ButtonVariant.outline}
          icon={<NotificationsIcon />}
        />
        <IconButton
          aria-label="Notifications"
          variant={ButtonVariant.link}
          icon={<NotificationsIcon />}
        />
        <IconButton
          aria-label="Settings"
          color={ButtonColor.secondary}
          icon={<SettingsIcon />}
        />
        <IconButton
          aria-label="Settings"
          color={ButtonColor.secondary}
          variant={ButtonVariant.outline}
          icon={<SettingsIcon />}
        />
        <IconButton
          aria-label="Settings"
          color={ButtonColor.secondary}
          variant={ButtonVariant.link}
          icon={<SettingsIcon />}
        />
        <IconButton
          aria-label="Correct"
          color={ButtonColor.success}
          icon={<CheckIcon />}
        />
        <IconButton
          aria-label="Correct"
          color={ButtonColor.success}
          variant={ButtonVariant.outline}
          icon={<CheckIcon />}
        />
        <IconButton
          aria-label="Correct"
          color={ButtonColor.success}
          variant={ButtonVariant.link}
          icon={<CheckIcon />}
        />
        <IconButton
          aria-label="Error"
          color={ButtonColor.danger}
          icon={<AlertIcon />}
        />
        <IconButton
          aria-label="Error"
          color={ButtonColor.danger}
          variant={ButtonVariant.outline}
          icon={<AlertIcon />}
        />
        <IconButton
          aria-label="Error"
          color={ButtonColor.danger}
          variant={ButtonVariant.link}
          icon={<AlertIcon />}
        />
        <IconButton
          aria-label="Notifications"
          disabled
          icon={<NotificationsIcon />}
        />
      </p>
      <p>
        <IconButton icon={<NotificationsIcon />}>Notifications</IconButton>
        <IconButton
          icon={<SettingsIcon />}
          color={ButtonColor.secondary}
          variant={ButtonVariant.outline}
        >
          Settings
        </IconButton>
        <IconButton
          icon={<CheckIcon />}
          color={ButtonColor.success}
          variant={ButtonVariant.link}
        >
          Submit
        </IconButton>
      </p>
    </>
  );
}

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 icon={icon}>Notification 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 } from 'react-magma-dom';
import { NotificationsIcon, InfoIcon } from 'react-magma-icons';

export function Example() {
  return (
    <>
      <IconButton icon={<NotificationsIcon />}>Icon Left</IconButton>
      <IconButton
        color={ButtonColor.secondary}
        icon={<InfoIcon />}
        iconPosition={ButtonIconPosition.right}
      >
        Icon Right
      </IconButton>
    </>
  );
}

Sizes

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

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

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

Shape

Icon only buttons have shape = round, by default.

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

export function Example() {
  return (
    <>
      <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}
      />
    </>
  );
}

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>
        Full-Width Notifications Button
      </IconButton>
      <IconButton
        icon={<NotificationsIcon />}
        isFullWidth
        iconPosition={ButtonIconPosition.right}
      >
        Full-Width Notifications Button
      </IconButton>

      <IconButton
        icon={<NotificationsIcon aria-label="Notifications" />}
        isFullWidth
      />
    </>
  );
}

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.

Icon Counter: 0 | Text Icon Counter: 0

import React from 'react';
import { IconButton } 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>
      <IconButton
        icon={<NotificationsIcon />}
        onClick={() => {
          setIconButtonCounter(count => count + 1);
        }}
      >
        Click me
      </IconButton>
      <IconButton
        icon={<NotificationsIcon />}
        textPosition="left"
        onClick={() => {
          setTextIconButtonCounter(count => count + 1);
        }}
      >
        Click me
      </IconButton>
      <IconButton
        disabled
        icon={<NotificationsIcon />}
        onClick={() => {
          setIconButtonCounter(count => count + 1);
        }}
      >
        Click me if you can
      </IconButton>
    </>
  );
}

Testing

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

<IconButton data-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.

= required prop

Property	Type	Default	Description
aria-label	string	-	The text the screen reader will announce. Required for icon-only buttons
children	node	-	The content of the component. If no children are provided, the button will render in an icon only style
color	enum, one of: `ButtonColor.primary` `ButtonColor.secondary` `ButtonColor.success` `ButtonColor.danger` `ButtonColor.marketing`	primary	The color of the button, indicating its function in the UI
disabled	boolean	false	If true, element is disabled
icon Required	React Element	-	Icon to display within the component
iconPosition	enum, one of: `ButtonIconPosition.left` `ButtonIconPosition.right`	right	Position within the button for the icon to appear
isFullWidth	boolean	false	If true, the button will take up the full width of its container
isInverse	boolean	false	If true, the component will have inverse styling to better appear on a dark background
shape	enum, one of: `ButtonShape.fill` `ButtonShape.leftCap` `ButtonShape.rightCap` `ButtonShape.round`	round	Defines the border radius
size	enum, one of: `ButtonSize.large` `ButtonSize.medium` `ButtonSize.small`	medium	The relative size of the button
testId	string	-	Test ID attached to an internal element as `data-testid` for consumer testing
textTransform	enum, one of: `ButtonTextTransform.uppercase` `ButtonTextTransform.none`	uppercase	Determines whether the button appears in all-caps
type	enum, one of: `ButtonType.button` `ButtonType.submit` `ButtonType.reset`	button	The type attribute of the button
variant	enum, one of: `ButtonVariant.solid` `ButtonVariant.outline` `ButtonVariant.link`	solid	The variant of the button