Button

Using Grommet for HPE?See Button examples and guidance.

A grommet Button is used for anything that looks like a button on the screen. If an href is provided, it will be rendered in the DOM with <a/>. An Anchor component should be used for inline anchors within textual contexts.

In May 2020, we enhanced Button to have three kinds, outlined below. In order to maintain backwards compatibility, this approach is only available when the theme being used defines button.default.

default

The majority of Buttons on the page. Their affordance is primarily driven by their context, in a Nav in a Header or Sidebar, the corner of a tile or card, etc.

primary

The primary call to action. There should typically be at most one primary Button on the screen. In a Form context, it signifies the action bound to the enter key that will submit the form.

secondary

When there isn’t enough context to indicate its affordance, or when it should call extra attention to itself but isn’t the primary call to action, use a secondary Button. Secondary buttons are only available when the underlying theme being used defines button.default.

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

string

"a user friendly label for screen readers"

active

Whether the button is active.

boolean

true

false

alignSelf

How to align along the cross axis when contained in a Box or along the column axis when contained in a Grid.

string

"start"

"center"

"end"

"stretch"

"baseline"

as

The DOM tag or react component to use for the element.

string

The name of a component.

"div"

function

() => {}

element

A specific element to use, such as a router element like Link from react-router-dom.

Link

badge

An indicator to show on the top-right of the Button. For accessibility, supplement the badge by adding an a11yTitle to the Button which provides a useful message to screen readers. For example, "2 unread notifications".

boolean

When badge is a boolean, the badge will be a circle with background color 'brand'.

true

false

element

<Box>...</Box>

number

When badge is a number, that number will appear inside the badge.

object

When badge is an object, background refers to the background color of the badge, value refers to either the numeric value that appears within the badge or a boolean if background has been defined on the object but no numeric content is desired, and max refers to the max value that can appear inside the badge. For example, if value is 10 and max is 9, the content in the badge will be displayed as 9+.


{
  background: {
    color: "...",
    dark: "...",
    image: "string",
    position: "string",
    opacity: "...",
    repeat: "...",
    size: "...",
    light: "string"
  }
  max: number,
  value: "..."
  }

where color could be:

"string"

{ dark: "string", light: "string" }

where dark could be:

boolean

"string"

where opacity could be:

boolean

number

"weak"

"medium"

"strong"

where repeat could be:

"no-repeat"

"repeat"

"string"

where size could be:

"cover"

"contain"

"string"

where value could be:

boolean

number

busy

Whether the button is in a busy state and should display an animation to indicate this.

boolean

true

false

children

Function that can be called to render the visual representation. When Button has children, it is styled as a plain button.

function

'disabled', 'hover', and 'focus' can be passed as an argument that would then return a react element.

({ disabled, hover, focus }) => {<Box>...</Box>}

object

node

<Box>...</Box>

color

Fill color for primary, label color for plain, border color otherwise. If button.default is defined in the theme, the color prop will fill the background color for primary and secondary button types. Color prop will change the text color for default button.

string

A hex, name, or rgb value.

"control"

object

An object with a color for dark and light modes.

 { dark: "string", light: "string" }

disabled

Whether the button is disabled.

boolean

true

false

fill

Whether the button expands to fill all of the available width and/or height.

string

"horizontal"

"vertical"

boolean

true

false

focusIndicator

Whether when 'plain' it should receive a focus outline.

boolean

true

false

gap

The amount of spacing between icon and label in the button.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

"string"

gridArea

The name of the area to place this inside a parent Grid.

string

"a parent grid area name"

hoverIndicator

The hover indicator to apply when the user is mousing over the button. This prop is meant to be used only with plain Buttons.

boolean

true

false

string

"background"

object

An object defining the background or the background and elevation.


{
  color: "...",
  dark: "...",
  image: "string",
  position: "string",
  opacity: "...",
  repeat: "...",
  size: "...",
  light: "string"
}


{
  background: {
    color: "...",
    dark: "...",
    image: "string",
    position: "string",
    opacity: "...",
    repeat: "...",
    size: "...",
    light: "string"
  },
  elevation: "..."
}

where color could be:

"string"

{ dark: "string", light: "string" }

where dark could be:

boolean

"string"

where opacity could be:

boolean

number

"weak"

"medium"

"strong"

where repeat could be:

"no-repeat"

"repeat"

"string"

where size could be:

"cover"

"contain"

"string"

where elevation could be:

"none"

"xsmall"

"small"

"medium"

"large"

"xlarge"

"string"

href

If specified, the button will behave like an anchor tag.

string

"//my.com/path"

icon

Icon element to place in the button. For accessibility with screen readers, if using just an icon (no label), add an a11yTitle to the Button that describes the icon.

element

<Add />

justify

How to align the contents within the button.

string

"around"

"between"

"center"

"end"

"evenly"

"start"

"stretch"

label

Label text to place in the button.

string

"label"

node

<Box>...</Box>

margin

The amount of margin around the component.

string

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}

messages

Messages for a screenreader to announce when the button busy or success state changes.

object

{
  "busy": "button is in a busy state",
  "success": "button action succeeded"
}

onClick

Click handler. Not setting this property and not specifying a href causes the Button to be disabled.

function

() => {}

pad

The amount of padding around the Button contents.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"none"

"xxsmall"

"xsmall"

"small"

"medium"

"large"

"xlarge"

"any CSS size"

object

An object can be specified to distinguish horizontal padding, vertical padding, and padding on a particular side.


{
  vertical: "...",
  horizontal: "...",
  top: "...",
  bottom: "...",
  left: "...",
  right: "...",
  start: "...",
  end: "..."
}

plain

Whether this is a plain button with no border or pad. Non plain button will show both pad and border. When using the kind button (i.e. button.default on the theme), the usage of plain is deprecated.

boolean

true

false

primary

Whether this is a primary button. There should be at most one per page or screen.

boolean

true

false

reverse

Whether an icon and label should be reversed so that the icon is at the end of the anchor.

boolean

true

false

secondary

Whether this is a secondary button.

boolean

true

false

size

The possible sizes of Button, that impacts the overall Button padding, border radius, text size and line height. 'size' will not impact any icon related sizing.

string

"small"

"medium"

"large"

success

Whether the button is in a success state and should display an animation to indicate this.

boolean

true

false

target

Specifies where to display the URL defined in the href property.

string

"_self"

"_blank"

"_parent"

"_top"

"string"

tip

tooltip or a hint when hovering over the button.

string

If the value is a string and no a11yTitle value is provided, tip value will be used for the a11yTitle default value.

"example tooltip"

object


{
  content: node | "string",
  dropProps: {...}
  plain: boolean
}

type

The type of button. Set the type to submit for the default button on forms.

string

"button"

"reset"

"submit"

React/DOM Properties

At its core, the Button component is a regular <button> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for button elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

global.active.background.color

The background color when using active prop.

string

A hex, name, or rgb value.

"active"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

global.active.background.opacity

The value used for active button background opacity.

string

"medium"

number

0.5

global.active.color

The text color when using active prop.

string

A hex, name, or rgb value.

"black"

object

An object with a color for dark and light modes.

{ dark: "white", light: "black" }

global.hover.background

The background style when hovering.

string

A hex, name, or rgb value.

"active"

object

An object with a color for dark and light modes.

{ color: "active", opacity: "medium" }

global.hover.color

The text color when hovering.

string

A hex, name, or rgb value.

"black"

object

An object with a color for dark and light modes.

{ dark: "white", light: "black" }

global.edgeSize.small

The padding around an icon-only button.

string

"12px"

global.colors.control

The color of the border.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "white", light: "brand" }

global.colors.brand

The light version of the border.

string

"#7D4CDB"

global.colors.text

The color of the text label.

string

A hex, name, or rgb value.

"black"

object

An object with a color for dark and light modes.

{ dark: '#f8f8f8', light: '#444444' }

text.medium.size

The font size of the text label.

string

"18px"

text.medium.height

The line height of the text label.

string

"24px"

button.active.background.color

Background color when the button is active.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.active.border.color

The border color when the button is active.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.active.color

Label color when the button is active.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.active.extend

Any additional style for an active Button.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

button.active.default

Adjustments to the default Button style when the Button is active.

object

{
         background: string | object,
         border: string | object | array,
         color:  string | object,
         font: {
           weight: string | number,
         },
         icon: element,
         padding: {
           vertical: string,
           horizontal: string,
         },
         reverse: boolean,
         extend: any css,
       }

button.active.primary

Adjustments to the primary Button style when the Button is active. Only relevant for themes that have defined a value for button.default.

object

{
         background: string | object,
         border: string | object | array,
         color:  string | object,
         font: {
           weight: string | number,
         },
         icon: element,
         padding: {
           vertical: string,
           horizontal: string,
         },
         reverse: boolean,
         extend: any css,
       }

button.active.secondary

Adjustments to the secondary Button style when the Button is active. Only relevant for themes that have defined a value for button.default.

object

{
         background: string | object,
         border: string | object | array,
         color:  string | object,
         font: {
           weight: string | number,
         },
         icon: element,
         padding: {
           vertical: string,
           horizontal: string,
         },
         reverse: boolean,
         extend: any css,
       }

button.badge.container.background

The background of the badge.

string

"brand"

object

{ dark: "string", light: "string" }


{
  color: { dark: "string", light: "string" } | "string",
  dark: bool,
  image: "string",
  position: "string",
  opacity: bool | "string",
  repeat: "no-repeat" | "repeat",
  size: "cover" | "contain" | "string"
}

button.badge.container.extend

Any additional styles for the badge.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

button.badge.container.pad

When badge has a value, the amount of pad to apply.

string

T-shirt sizing based off the theme or a specific size in px, em, etc.

"small"

object

An object can be specified to distinguish horizontal padding, vertical padding, and padding on a particular side.


{
  vertical: "...",
  horizontal: "...",
  top: "...",
  bottom: "...",
  left: "...",
  right: "..."
}

button.badge.size.medium

The minimum width and height of the badge when the badge contains a value. If badge is a boolean, the default width and height will be one half of this value.

string

"24px"

button.badge.text.size.medium

The size of the text that is mapped according to 'button.badge.size.medium'.

string

"14px"

button.border.color

The color of the border.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.border.radius

The corner radius.

string

"18px"

button.border.width

The border width.

string

"2px"

button.color

The color of the text label.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.default.background.color

The color of the background for default buttons.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.default.background.opacity

The value used for default button background opacity.

string

"medium"

number

0.5

button.default.border.color

The color of the border for default buttons.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.default.color

The color of the label for default buttons.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.default.direction

The direction of the icon + label.

string

'row'

button.default.font.size

The size of the text label for default buttons.

string

'small'

button.default.font.weight

The weight of the text label for default buttons.

string

Any browser font-weight definition.

"normal"

"bold"

number

button.default.extend

Any additional style for a default button.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

button.default.padding.horizontal

The horizontal padding for a default button.

string

"22px"

button.default.padding.vertical

The vertical padding for a default button.

string

"4px"

button.disabled.color

Label color when the button is disabled.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.disabled.border.color

The border color when the button is disabled.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.disabled.background.color

Background color when the button is disabled.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.disabled.opacity

The opacity when the button is disabled.

number

0.3

button.disabled.extend

Any additional style for a disabled Button.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

button.disabled.default

Adjustments to the default Button style when the Button is disabled.

object

{}

button.disabled.primary

Adjustments to the primary Button style when the Button is disabled. Only relevant for themes that have defined a value for button.default.

object

{}

button.disabled.secondary

Adjustments to the secondary Button style when the Button is disabled. Only relevant for themes that have defined a value for button.default.

object

{}

button.hover.color

Label color when the button is hovered.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.hover.border.color

The border color when the button is hovered.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.hover.background.color

Background color when the button is hovered.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.hover.extend

Any additional style for a hovered Button.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

button.hover.default

Adjustments to the default Button style when the Button is hovered.

object

{}

button.hover.primary

Adjustments to the primary Button style when the Button is hovered. Only relevant for themes that have defined a value for button.default.

object

{}

button.hover.secondary

Adjustments to the secondary Button style when the Button is hovered. Only relevant for themes that have defined a value for button.default.

object

{}

button.padding.horizontal

The horizontal padding.

string

"22px"

button.padding.vertical

The vertical padding.

string

"4px"

button.primary.background.color

The color of the background for primary buttons. Only relevant for themes that have defined a value for button.default.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.primary.background.opacity

The value used for primary button background opacity. Only relevant for themes that have defined a value for button.default.

string

"medium"

number

0.5

button.primary.border.color

The color of the border for primary buttons. Only relevant for themes that have defined a value for button.default.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.primary.color

The color of the label for primary buttons.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.primary.direction

The direction of the icon + label.

string

'row'

button.primary.font.size

The size of the text label for primary buttons.

string

'small'

button.primary.font.weight

The weight of the text label for primary buttons.

string

Any browser font-weight definition.

"normal"

"bold"

number

button.primary.padding.horizontal

The horizontal padding for a primary button.

string

"22px"

button.primary.padding.vertical

The vertical padding for a primary button.

string

"4px"

button.primary.extend

Any additional style for a primary button.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

button.secondary.background.color

The color of the background for secondary buttons. Only relevant for themes that have defined a value for button.default.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.secondary.background.opacity

The value used for secondary button background opacity. Only relevant for themes that have defined a value for button.default.

string

"medium"

number

0.5

button.secondary.border.color

The color of the border for secondary buttons. Only relevant for themes that have defined a value for button.default.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.secondary.color

The color of the label for secondary buttons. Only relevant for themes that have defined a value for button.default.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

button.secondary.direction

The direction of the icon + label.

string

'row'

button.secondary.font.size

The size of the text label for secondary buttons.

string

'small'

button.secondary.font.weight

The weight of the text label for secondary buttons. Only relevant for themes that have defined a value for button.default.

string

Any browser font-weight definition.

"normal"

"bold"

number

button.secondary.padding.horizontal

The horizontal padding for a secondary button. Only relevant for themes that have defined a value for button.default.

string

"22px"

button.secondary.padding.vertical

The vertical padding for a secondary button. Only relevant for themes that have defined a value for button.default.

string

"4px"

button.secondary.extend

Any additional style for a secondary button. Only relevant for themes that have defined a value for button.default.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

button.size.small.border.radius

The border corner radius.

string

"18px"

button.size.small.pad.horizontal

The pad

string

"20px"

button.size.small.pad.vertical

The pad

string

"4px"

button.size.small.iconOnly.pad

Specify pad for iconOnly Buttons across button sizes.

string

"4px"

object

{ horizontal: string; vertical: string }

button.size.medium.border.radius

The border corner radius.

string

"18px"

button.size.medium.pad.horizontal

The pad

string

"22px"

button.size.medium.pad.vertical

The pad

string

"4px"

button.size.medium.iconOnly.pad

Specify pad for iconOnly Buttons across button sizes.

string

"4px"

object

{ horizontal: string; vertical: string }

button.size.large.border.radius

The border corner radius.

string

"24px"

button.size.large.pad.horizontal

The pad

string

"32px"

button.size.large.pad.vertical

The pad

string

"8px"

button.size.large.iconOnly.pad

Specify pad for iconOnly Buttons across button sizes.

string

"4px"

object

{ horizontal: string; vertical: string }

button.transition.duration

The length of time it will take for the element to transition between two states.

number

0.1

button.transition.properties

The CSS properties you want to add the transition to.

string

"color"

"background-color"

"border-color"

"box-shadow"

button.transition.timing

Describes how a transition will progress over one cycle of its duration and allowing it to change speed during its course.

string

ease-in-out

button.intelligentPad

This provides the ability to opt-out of the intelligent padding that automaticlly subtracts border width from button padding.

boolean

true

false

button.elevation

The elevation for a given button. Should reference an elevation namespace from theme.global.elevation.

string

'medium'

button.extend

Any additional style for the Button.

string

Any CSS.

css`color: 'blue'`

function

(props) => {}

tip.content

When using tip prop, any valid Box property for the Tip container.

object


{ 
  background: "background-contrast", 
  elevation: "small", 
  margin: "xsmall", 
  pad: { vertical: "xsmall", horizontal: "small" }, 
  round: "small"
}

tip.drop

When using tip prop, any valid Drop property for the Tooltip.

object


{
  align: { top: "bottom" },
  background: "none",
  elevation: "none",
  margin: "none"
}

global.focus.border.color

The border color of the component when in focus.

string

A hex, name, or rgb value.

"focus"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

global.focus.outline.color

The outline color around the component when in focus.

string

A hex, name, or rgb value.

"brand"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

global.focus.outline.size

The size of the outline around the component when in focus.

string

"2px"

global.focus.shadow.color

The shadow color around the component when in focus.

string

"focus"

object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

global.focus.shadow.size

The size of the shadow around the component when in focus.

string

"2px"

global.control.disabled.opacity

The opacity when a component is disabled.

number

0.3

button.skeleton

Any Skeleton properties which will be applied to the Button when in skeleton mode. For the Button to be in skeleton mode, use the 'skeleton' property on a parent Box.

object

{ width: { min: '100px' }}