ActionButton

ActionButtons allow users to perform an action or mark a selection. They’re used for similar, task-based options within a workflow, and are ideal for interfaces where buttons aren’t meant to draw a lot of attention.

installyarn add @react-spectrum/button
version3.0.0-rc.2
usageimport {ActionButton} from '@react-spectrum/button'
View guidelines
Spectrum
View repository
GitHub
View package
NPM

Example#

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

<ActionButton>
  <Edit />
  <Text>Edit</Text>
</ActionButton>

Content#

ActionButtons can have a label, an icon, or both. An icon is provided by passing an icon component as a child to the ActionButton. A visible label can be provided by passing a string or a Text component as a child, depending on whether the ActionButton has an accompanying icon.

<ActionButton>
  Label only
</ActionButton>
<ActionButton>
  <Edit />
  <Text>Icon + Label</Text>
</ActionButton>
<ActionButton aria-label="Icon only">
  <Edit />
</ActionButton>

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 an ActionButton, a localized string should be passed to the children or aria-label prop.

Events#

ActionButtons 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 (
   <ActionButton onPress={() => setCount(c => c + 1)}>{count} Edits</ActionButton>
  );
}

Props#

NameTypeDefaultDescription
isQuietboolean—Whether the ActionButton should be displayed with a quiet style.
isSelectedboolean—Whether the ActionButton should be displayed with a selected state.
isEmphasizedboolean—Whether the ActionButton should be displayed with a emphasized style.
holdAffordanceboolean—Whether the ActionButton should be displayed with a hold icon.
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#

Quiet#

View guidelines

<ActionButton isQuiet>Action!</ActionButton>

Selected#

View guidelines

<ActionButton isSelected>Action!</ActionButton>

Emphasis#

View guidelines

Note that the styling provided by the isEmphasized prop is only applied when the isSelected prop is true.

<ActionButton isEmphasized isSelected>Action!</ActionButton>

Hold Affordance#

View guidelines

<ActionButton holdAffordance aria-label="Edit">
  <Edit />
</ActionButton>

Disabled#

View guidelines

<ActionButton isDisabled>Action!</ActionButton>