Button

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.

"a user friendly label for screen readers"

active

Whether the button is active.

truefalse

alignSelf

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

"start"

"center"

"end"

"stretch"

as

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

"string""function"

children

Function that can be called to render the visual representation. Button can take in Children as a function, node, or object. For example, 'disabled', 'hover', and 'focus' can be passed as an argument that would then return a react element. children={({ disabled, hover, focus }) => <Box...>{...}</Box>}. When Button has children, it is styled as a plain button.

"function""object""node"

color

Fill color for primary, label color for plain, border color otherwise.

"control"

disabled

Whether the button is disabled.

truefalse

fill

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

"horizontal""vertical"truefalse

focusIndicator

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

truefalse

gap

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

"none""xxsmall""xsmall""small""medium""large""xlarge""string"

gridArea

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

"a parent grid area name"

hoverIndicator

The hover indicator to apply when the user is mousing over the button. An object can be also be specified for color index support: {background: 'neutral-2'}. This prop is meant to be used only with plain Buttons.

truefalse"string""background"

{

color:

"string,"

dark:

"boolean""string,"

image:

"string,"

light:

"string,"

position:

"string,"

opacity:

"string""boolean""number""weak""medium""strong,"

repeat:

"no-repeat""repeat""string,"

size:

"cover""contain""string"

}

href

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

"//my.com/path"

icon

Icon element to place in the button.

<Add />

label

Label text to place in the button.

"Add"

<Box>...</Box>

margin

The amount of margin around the component. An object can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.

"xsmall"

"small"

"medium"

"large"

"xlarge"

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

onClick

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

() => {}

plain

Whether this is a plain button with no border or pad. Non plain button will show both pad and border. The plain button has no border and unless the icon prop exist it has no pad as well. When using the kind button (i.e. button.default on the theme), the usage of plain is deprecated.

truefalse

primary

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

truefalse

reverse

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

truefalse

secondary

Whether this is a secondary button.

truefalse

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.

"small""medium""large"

target

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

"_self""_blank""_parent""_top""string"

tip

tooltip or a hint when hovering over the button.

"string"

{

content:

"node""string,"

dropProps:

{

}

plain: boolean

}

type

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

"button""reset""submit"

Theme

global.active.background.color

The background color when using active prop.

"active"

global.active.background.opacity

The value used for active button background opacity.

"medium"

global.active.color

The text color when using active prop.

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

global.hover.background

The background style when hovering.

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

global.hover.color

The text color when hovering.

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

global.edgeSize.small

The padding around an icon-only button.

"12px"

global.colors.control

The color of the border.

{"dark": "accent-1", "light": "brand"}

global.colors.brand

The light version of the border.

"#7D4CDB"

global.colors.text

The color of the text label.

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

text.medium.size

The font size of the text label.

"18px"

text.medium.height

The line height of the text label.

"24px"

button.active.background.color

Background color when the button is active.

string | { dark: string, light: string }

button.active.border.color

The border color when the button is active.

string | { dark: string, light: string }

button.active.color

Label color when the button is active.

"active-text"

button.active.extend

Any additional style for an active Button.

"any CSS"

(props) => {}

button.active.default

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

object

button.active.primary

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

{}

button.active.secondary

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

{}

button.border.color

The color of the border.

string | { dark: string, light: string }

button.border.radius

The corner radius.

"18px"

button.border.width

The border width.

"2px"

button.color

The color of the text label.

string | { dark: string, light: string }

button.default.background.color

The color of the background for default buttons.

string | { dark: string, light: string }

button.default.background.opacity

The value used for default button background opacity.

number | string

button.default.border.color

The color of the border for default buttons.

string | { dark: string, light: string }

button.default.color

The color of the label for default buttons.

string | { dark: string, light: string }

button.default.font.weight

The weight of the text label for default buttons.

string | number

button.default.extend

Any additional style for a default button.

"any CSS"

(props) => {}

button.default.padding.horizontal

The horizontal padding for a default button.

string

button.default.padding.vertical

The vertical padding for a default button.

string

button.disabled.color

Label color when the button is disabled.

string | { dark: string, light: string }

button.disabled.border.color

The border color when the button is disabled.

string | { dark: string, light: string }

button.disabled.background.color

Background color when the button is disabled.

string | { dark: string, light: string }

button.disabled.opacity

The opacity when the button is disabled.

0.3

button.disabled.extend

Any additional style for a disabled Button.

"any CSS"

(props) => {}

button.disabled.default

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

{}

button.disabled.primary

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

{}

button.disabled.secondary

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

{}

button.hover.color

Label color when the button is hovered.

string | { dark: string, light: string }

button.hover.border.color

The border color when the button is hovered.

string | { dark: string, light: string }

button.hover.background.color

Background color when the button is hovered.

string | { dark: string, light: string }

button.hover.extend

Any additional style for a hovered Button.

"any CSS"

(props) => {}

button.hover.default

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

{}

button.hover.primary

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

{}

button.hover.secondary

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

{}

button.padding.horizontal

The horizontal padding.

"22px"

button.padding.vertical

The vertical padding.

"4px"

button.primary.background.color

The color of the background for primary buttons.

string | { dark: string, light: string }

button.primary.background.opacity

The value used for primary button background opacity.

number | string

button.primary.border.color

The color of the border for primary buttons.

string | { dark: string, light: string }

button.primary.color

The color of the label for primary buttons.

string | { dark: string, light: string }

button.primary.font.weight

The weight of the text label for primary buttons.

string | number

button.primary.padding.horizontal

The horizontal padding for a primary button.

string

button.primary.padding.vertical

The vertical padding for a primary button.

string

button.primary.extend

Any additional style for a primary button.

"any CSS"

(props) => {}

button.secondary.background.color

The color of the background for secondary buttons.

string | { dark: string, light: string }

button.secondary.background.opacity

The value used for secondary button background opacity.

number | string

button.secondary.border.color

The color of the border for secondary buttons.

string | { dark: string, light: string }

button.secondary.color

The color of the label for secondary buttons.

string | { dark: string, light: string }

button.secondary.font.weight

The weight of the text label for secondary buttons.

string | number

button.secondary.padding.horizontal

The horizontal padding for a secondary button.

string

button.secondary.padding.vertical

The vertical padding for a secondary button.

string

button.secondary.extend

Any additional style for a secondary button.

"any CSS"

(props) => {}

button.size.small.border.radius

The border corner radius.

"18px"

button.size.small.pad.horizontal

The pad

"20px"

button.size.small.pad.vertical

The pad

"4px"

button.size.medium.border.radius

The border corner radius.

"18px"

button.size.medium.pad.horizontal

The pad

"22px"

button.size.medium.pad.vertical

The pad

"4px"

button.size.large.border.radius

The border corner radius.

"24px"

button.size.large.pad.horizontal

The pad

"32px"

button.size.large.pad.vertical

The pad

"8px"

button.transition.duration

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

0.1

button.transition.properties

The CSS properties you want to add the transition to.

"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.

"ease-in-out"

button.extend

Any additional style for the Button.

tip.content

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

{
  "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.

{"align": {"top": "bottom"}}

global.focus.border.color

The border color of the component when in focus.

"focus"

global.focus.outline.color

The outline color around the component when in focus.

string | { dark: string, light: string }

global.focus.outline.size

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

string

global.focus.shadow.color

The shadow color around the component when in focus.

"focus"

global.focus.shadow.size

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

"2px"

global.control.disabled.opacity

The opacity when a component is disabled.

0.3