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'
View guidelines
Spectrum
View repository
GitHub
View package
NPM

Example#

<Button variant="cta">Test</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>

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>
  );
}

Props#

NameTypeDefaultDescription
iconReactElement—An icon to display in the button
variant'cta' | 'overBackground' | 'primary' | 'secondary' | 'negative'—The visual style of the button.
isQuietboolean—Whether the button should be displayed with a quiet style.
isDisabledboolean—Whether the button is disabled
elementTypestring | JSXElementConstructor<any>"button"The HTML element or React element used to render the button, e.g. "div", "a", or RouterLink.
childrenReactNode—The content to display in the button.
hrefstring—A URL to link to if elementType="a".
targetstring—The target window for the link.
autoFocusboolean—Whether the element should receive focus on render
UNSAFE_classNamestring—
UNSAFE_styleCSSProperties—
Events
NameTypeDefaultDescription
onPress(e: PressEvent) => void—Handler that is called when the press is released over the target.
onPressStart(e: PressEvent) => void—Handler that is called when a press interaction starts.
onPressEnd(e: PressEvent) => void—

Handler that is called when a press interation ends, either over the target or when the pointer leaves the target.

onPressChange(isPressed: boolean) => void—Handler that is called when the press state changes.
onPressUp(e: PressEvent) => void—

Handler that is called when a press is released over the target, regardless of whether it started on the target or not.

onFocus(e: FocusEvent) => void—Handler that is called when the element receives focus.
onBlur(e: FocusEvent) => void—Handler that is called when the element loses focus.
onFocusChange(isFocused: boolean) => void—Handler that is called when the element's focus status changes.
onKeyDown(e: KeyboardEvent) => void—Handler that is called when a key is pressed.
onKeyUp(e: KeyboardEvent) => void—Handler that is called when a key is released.
Layout
NameTypeDefaultDescription
flexstring | number | boolean—
flexGrownumber—
flexShrinknumber—
flexBasisnumber | string—
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
rolestring—
idstring—
tabIndexnumber—
aria-labelstring—Defines a string value that labels the current element.
aria-labelledbystring—Identifies the element (or elements) that labels the current element.
aria-describedbystring—Identifies the element (or elements) that describes the object.
aria-controlsstring—Identifies the element (or elements) whose contents or presence are controlled by the current element.
aria-ownsstring—

Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between DOM elements where the DOM hierarchy cannot be used to represent the relationship.

aria-hiddenboolean | 'false' | 'true'—Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

Visual Options#

Call To Action#

View guidelines

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

Primary#

View guidelines

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

Secondary#

View guidelines

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

Over Background#

View guidelines

<div style={{backgroundColor: 'rgb(15, 121, 125)', padding: '15px 20px'}}>
  <Button variant="overBackground">Test</Button>
  <Button variant="overBackground" isQuiet>Test</Button>
</div>

Negative#

View guidelines

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