Button | Mineral UI

The Button component represents a clickable button. Buttons draw attention to actions that can be performed in your app. Buttons are used to trigger any sort of event.

Examples #

Import Syntax #

import Button from 'mineral-ui/Button';

Buttons trigger different actions around the page. Primary Buttons are used once per container, usually as the main call to action for the page. Overuse of primary buttons could make the interface feel too busy.

<DemoLayout>
  <Button primary>Default</Button>
  <Button variant="success" primary>Success</Button>
  <Button variant="warning" primary>Warning</Button>
  <Button variant="danger" primary>Danger</Button>
  <Button primary disabled>Disabled</Button>
</DemoLayout>

Default #

Regular Buttons are good for secondary actions when grouped with another primary button. These Buttons are not impactful enough to represent the primary action in a container.

<DemoLayout>
  <Button>Default</Button>
  <Button variant="success">Success</Button>
  <Button variant="warning">Warning</Button>
  <Button variant="danger">Danger</Button>
  <Button disabled>Disabled</Button>
</DemoLayout>

Minimal #

Use for less-important actions, or if there are a lot of other buttons on screen.

<DemoLayout>
  <Button minimal>Default</Button>
  <Button variant="success" minimal>Success</Button>
  <Button variant="warning" minimal>Warning</Button>
  <Button variant="danger" minimal>Danger</Button>
  <Button disabled minimal>Disabled</Button>
</DemoLayout>

Sizes #

To provide hierarchy to actions on your page, change Button impact with the size attribute.

For a Button whose width is defined by its container, use fullWidth.

<DemoLayout>
  <Button size="small">Small</Button>
  <Button size="medium">Medium</Button>
  <Button>Large</Button>
  <Button size="jumbo">Jumbo</Button>
  <Button fullWidth>Full Width</Button>
</DemoLayout>

Buttons with Icons #

Buttons can contain Icons at their start, end, or both.

small Buttons use small Icons; medium and large Buttons use medium Icons; jumbo Buttons use large Icons.

() => {
  const icon = <IconCloud />;

  return (
    <DemoLayout>
      <Button iconStart={icon}>Start icon</Button>
      <Button iconEnd={icon}>End icon</Button>
      <Button iconStart={icon} iconEnd={icon}>Both icons</Button>
      <br /><br />
      <Button iconStart={icon} primary>Primary</Button>
      <Button iconStart={icon} minimal>Minimal</Button>
      <Button iconStart={icon} variant="danger">Danger</Button>
      <Button iconStart={icon} variant="success">Success</Button>
      <Button iconStart={icon} variant="warning">Warning</Button>
      <Button iconStart={icon} disabled>Disabled</Button>
      <br /><br />
      <Button iconStart={icon} size="small">Small</Button>
      <Button iconStart={icon} size="medium">Medium</Button>
      <Button iconStart={icon}>Large</Button>
      <Button iconStart={icon} size="jumbo">Jumbo</Button>
    </DemoLayout>
  );
}

Icon-Only Buttons #

Buttons that contain only Icons can use either iconStart or iconEnd props and must have an aria-label provided.

Use icon-only Buttons sparingly. The meaning of the Button can be diluted without a visual label.

() => {
  const icon = <IconCloud />;

  return (
    <DemoLayout>
      {/* Icon as prop; no text. aria-label applied to Button. */}
      <Button iconStart={icon} aria-label="Cloud" />
      {/* primary */}
      <Button iconStart={icon} primary aria-label="Cloud" />
      {/* minimal */}
      <Button iconStart={icon} minimal aria-label="Cloud" />
      {/* small */}
      <Button iconStart={icon} size="small" aria-label="Cloud" />
      {/* large */}
      <Button iconStart={icon} size="medium" aria-label="Cloud" />
      {/* jumbo */}
      <Button iconStart={icon} size="jumbo" aria-label="Cloud" />
    </DemoLayout>
  );
}

Circular Buttons #

Buttons can be made circular. Such Buttons should not have any text.

() => {
  const icon = <IconCloud />;

  return (
    <DemoLayout>
      <Button iconStart={icon} circular aria-label="Cloud" />
      {/* primary */}
      <Button iconStart={icon} circular primary aria-label="Cloud" />
      {/* minimal */}
      <Button iconStart={icon} circular minimal aria-label="Cloud" />
      {/* small */}
      <Button iconStart={icon} circular size="small" aria-label="Cloud" />
      {/* large */}
      <Button iconStart={icon} circular size="medium" aria-label="Cloud" />
      {/* jumbo */}
      <Button iconStart={icon} circular size="jumbo" aria-label="Cloud" />
    </DemoLayout>
  );
}

Link #

Link with Button styling. See the Link component for more conventionally styled links.

Link

<Button as="a" href="#link">Link</Button>

Truncation #

Long button text is truncated when necessary.

() => {
  const  icon = <IconCloud />;

  return (
    <FixedWidthLayout>
      <Button>Supercalifragilisticexpialidocious</Button>
      <Button iconStart={icon}>Start icon truncation</Button>
      <Button iconEnd={icon}>End icon truncation</Button>
      <Button iconStart={icon} iconEnd={icon}>Both icons truncation</Button>
    </FixedWidthLayout>
  )
}

Bidirectionality #

Buttons support right-to-left (RTL) languages. Buttons with Icons are reversed when the direction theme variable is set to rtl. A subset of Icons that convey directionality will be reversed.

<div dir="rtl">
  <ThemeProvider theme={{ direction: 'rtl' }}>
    <Button iconStart={<IconBackspace />}>قم بعمل ما</Button>
  </ThemeProvider>
</div>

API & Theme #

Button Props #

The Button component takes the following React props.

Name	Type	Default	Description
children	React$Node		Rendered content of the component
circular	boolean		Displays a circular Button
disabled	boolean		Disables the Button
fullWidth	boolean		Stretch Button to fill its container
iconEnd	React$Element		Icon that goes after the children
iconStart	React$Element		Icon that goes before the children
minimal	boolean		Display a minimal Button
onClick			Called with the click event
primary	boolean		Display a primary Button
size	'small' \| 'medium' \| 'large' \| 'jumbo'	'large'	Available sizes
type	string		Available types
variant	'danger' \| 'success' \| 'warning'		Available variants

Undocumented properties, including as and css, will be applied to the root element.

Button Theme Variables #

These variables can be used as hooks to override this component's style at either a local or global level. The theme referenced below is whatever theme is available from props to the instance of this component.

Variable	Value
Button_backgroundColor	theme.backgroundColor
Button_backgroundColor_active	theme.backgroundColor_active
Button_backgroundColor_focus	theme.backgroundColor_focus
Button_backgroundColor_hover	theme.backgroundColor_hover
Button_backgroundColor_minimal_active	theme.backgroundColor_active
Button_backgroundColor_minimal_hover	theme.backgroundColor_hover
Button_backgroundColor_primary	theme.backgroundColor_themePrimary
Button_backgroundColor_primary_active	theme.backgroundColor_themePrimary_active
Button_backgroundColor_primary_focus	theme.backgroundColor_themePrimary_focus
Button_backgroundColor_primary_hover	theme.backgroundColor_themePrimary_hover
Button_borderColor	theme.borderColor
Button_borderColor_active	theme.borderColor_theme_active
Button_borderColor_focus	theme.borderColor_theme_focus
Button_borderColor_hover	theme.borderColor_theme_hover
Button_borderRadius	theme.borderRadius_1
Button_borderWidth	1px
Button_boxShadow_focus	0 0 0 1px boxShadow_focusInner, 0 0 0 2px borderColor_theme_focus
Button_color	theme.color_theme
Button_color_minimal	theme.color_theme
Button_color_primary	theme.color_themePrimary
Button_fontWeight	theme.fontWeight_semiBold
Button_paddingHorizontal	theme.space_inset_sm
Button_paddingIconOnly_small	0.1875em
Button_paddingIconOnly_medium	0.4375em
Button_paddingIconOnly_large	0.4375em
Button_paddingIconOnly_jumbo	0.8125em
Button_height_small	theme.size_small
Button_height_medium	theme.size_medium
Button_height_large	theme.size_large
Button_height_jumbo	theme.size_jumbo
ButtonContent_fontSize	theme.fontSize_ui
ButtonContent_fontSize_small	0.75em
ButtonIcon_color	theme.icon_color_theme
ButtonIcon_margin	theme.space_inset_sm

Usage #

When/How to Use #

A Button should be used whenever you need to trigger an action in your app. Buttons should have concise labeling indicating to your user what will happen when the Button is clicked. The color of the button should be chosen according to the intent of the action.

For example, if clicking a Button will make a potentially destructive action, use variant="danger" instead of "success".

Best Practices #

Use the appropriate variant for your intent.

Don't use a variant that differs from intent, as this will cause confusion.

Clearly label button actions to be predictable for frictionless interaction. Exceptions would include "Ok", "Cancel", etc. which should be used sparingly. Labels should be structured: <verb> <noun>.

Don't use "click me" or other vague messaging. Users should know exactly what will happen when they click a Button.