Button

Buttons allow users to perform an action or to navigate to another page. They have multiple styles for various needs, and are ideal for calling attention to where a user needs to do something in order to move forward in a flow.

installyarn add @react-spectrum/button
version3.0.0-rc.2
usageimport {Button} from '@react-spectrum/button'

Example#


<Button variant="cta">Save</Button>
<Button variant="cta">Save</Button>
<Button variant="cta">
  Save
</Button>

Content#


Buttons can have a label, and icon, or both. An icon is provided by passing an icon component to the icon prop. A visible label can be provided by passing children.

import {Text} from '@react-spectrum/typography';

<Button variant="primary">Label only</Button>
<Button variant="primary">
  <Bell />
  <Text>Icon + Label</Text>
</Button>
<Button variant="primary" aria-label="Icon only">
  <Bell />
</Button>
import {Text} from '@react-spectrum/typography';

<Button variant="primary">Label only</Button>
<Button variant="primary">
  <Bell />
  <Text>Icon + Label</Text>
</Button>
<Button variant="primary" aria-label="Icon only">
  <Bell />
</Button>
import {Text} from '@react-spectrum/typography';

<Button variant="primary">
  Label only
</Button>
<Button variant="primary">
  <Bell />
  <Text>
    Icon + Label
  </Text>
</Button>
<Button
  variant="primary"
  aria-label="Icon only">
  <Bell />
</Button>

Accessibility#

If no visible label is provided (e.g. an icon only button), an alternative text label must be provided to identify the control for accessibility. This should be added using the aria-label prop.

Internationalization#

In order to internationalize a button, a localized string should be passed to the children or aria-label prop.

Events#


Buttons support user interactions via mouse, keyboard, and touch. You can handle all of these via the onPress prop.

The following example uses an onPress handler to update a counter stored in React state.

function Example() {
  let [count, setCount] = React.useState(0);

  return (
    <Button variant="primary" onPress={() => setCount((c) => c + 1)}>
      {count} Dogs
    </Button>
  );
}
function Example() {
  let [count, setCount] = React.useState(0);

  return (
    <Button
      variant="primary"
      onPress={() => setCount((c) => c + 1)}>
      {count} Dogs
    </Button>
  );
}
function Example() {
  let [
    count,
    setCount
  ] = React.useState(0);

  return (
    <Button
      variant="primary"
      onPress={() =>
        setCount(
          (c) => c + 1
        )
      }>
      {count} Dogs
    </Button>
  );
}

Props#


NameTypeDefaultDescription
variant'cta' | 'overBackground' | 'primary' | 'secondary' | 'negative'The visual style of the button.
isQuietbooleanWhether the button should be displayed with a quiet style.
type'button''submit''reset'"button"The behavior of the button when used in an HTML form.
isDisabledbooleanWhether the button is disabled
elementTypestringJSXElementConstructor<any>"button"The HTML element or React element used to render the button, e.g. "div", "a", or RouterLink.
childrenReactNodeThe content to display in the button.
hrefstringA URL to link to if elementType="a".
targetstringThe target window for the link.
autoFocusbooleanWhether the element should receive focus on render
UNSAFE_classNamestring
UNSAFE_styleCSSProperties
Events
NameTypeDefaultDescription
onPress( (e: PressEvent )) => voidHandler that is called when the press is released over the target.
onPressStart( (e: PressEvent )) => voidHandler that is called when a press interaction starts.
onPressEnd( (e: PressEvent )) => voidHandler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressChange( (isPressed: boolean )) => voidHandler that is called when the press state changes.
onPressUp( (e: PressEvent )) => voidHandler that is called when a press is released over the target, regardless of whether it started on the target or not.
onFocus( (e: FocusEvent )) => voidHandler that is called when the element receives focus.
onBlur( (e: FocusEvent )) => voidHandler that is called when the element loses focus.
onFocusChange( (isFocused: boolean )) => voidHandler that is called when the element's focus status changes.
onKeyDown( (e: KeyboardEvent )) => voidHandler that is called when a key is pressed.
onKeyUp( (e: KeyboardEvent )) => voidHandler that is called when a key is released.
Layout
NameTypeDefaultDescription
flexstringnumberboolean
flexGrownumber
flexShrinknumber
flexBasisnumberstring
alignSelf'auto' | 'normal' | 'start' | 'end' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'center' | 'stretch'
justifySelf'auto' | 'normal' | 'start' | 'end' | 'flex-start' | 'flex-end' | 'self-start' | 'self-end' | 'center' | 'left' | 'right' | 'stretch'
flexOrdernumber
gridAreastring
gridColumnstring
gridRowstring
gridColumnStartstring
gridColumnEndstring
gridRowStartstring
gridRowEndstring
Spacing
NameTypeDefaultDescription
marginDimensionValue
marginTopDimensionValue
marginLeftDimensionValue
marginRightDimensionValue
marginBottomDimensionValue
marginStartDimensionValue
marginEndDimensionValue
marginXDimensionValue
marginYDimensionValue
Sizing
NameTypeDefaultDescription
widthDimensionValue
minWidthDimensionValue
maxWidthDimensionValue
heightDimensionValue
minHeightDimensionValue
maxHeightDimensionValue
Positioning
NameTypeDefaultDescription
position'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'
topDimensionValue
bottomDimensionValue
leftDimensionValue
rightDimensionValue
startDimensionValue
endDimensionValue
zIndexnumber
isHiddenboolean
Accessibility
NameTypeDefaultDescription
idstring
tabIndexnumber
aria-expandedbooleanIndicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
aria-haspopupboolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog'Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
aria-controlsstringIdentifies the element (or elements) whose contents or presence are controlled by the current element.
aria-pressedbooleanIndicates the current "pressed" state of toggle buttons.
aria-labelstringDefines a string value that labels the current element.
aria-labelledbystringIdentifies the element (or elements) that labels the current element.
aria-describedbystringIdentifies the element (or elements) that describes the object.
aria-detailsstringIdentifies the element (or elements) that provide a detailed, extended description for the object.

Visual options#


Call to action#

View guidelines

<Button variant="cta">Save</Button>
<Button variant="cta">Save</Button>
<Button variant="cta">
  Save
</Button>

Primary#

View guidelines

<Button variant="primary">Save</Button>
<Button variant="primary" isQuiet>Save</Button>
<Button variant="primary">Save</Button>
<Button variant="primary" isQuiet>Save</Button>
<Button variant="primary">
  Save
</Button>
<Button
  variant="primary"
  isQuiet>
  Save
</Button>

Secondary#

View guidelines

<Button variant="secondary">Save</Button>
<Button variant="secondary" isQuiet>Save</Button>
<Button variant="secondary">Save</Button>
<Button variant="secondary" isQuiet>Save</Button>
<Button variant="secondary">
  Save
</Button>
<Button
  variant="secondary"
  isQuiet>
  Save
</Button>

Over background#

View guidelines

<View backgroundColor="positive" padding="size-300">
  <Button variant="overBackground">Save</Button>
  <Button variant="overBackground" isQuiet>Save</Button>
</View>
<View backgroundColor="positive" padding="size-300">
  <Button variant="overBackground">Save</Button>
  <Button variant="overBackground" isQuiet>Save</Button>
</View>
<View
  backgroundColor="positive"
  padding="size-300">
  <Button variant="overBackground">
    Save
  </Button>
  <Button
    variant="overBackground"
    isQuiet>
    Save
  </Button>
</View>

Negative#

View guidelines

<Button variant="negative">Save</Button>
<Button variant="negative" isQuiet>Save</Button>
<Button variant="negative">Save</Button>
<Button variant="negative" isQuiet>Save</Button>
<Button variant="negative">
  Save
</Button>
<Button
  variant="negative"
  isQuiet>
  Save
</Button>