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.1
usageimport {ActionButton} from '@react-spectrum/button'
View guidelines
Spectrum
View repository
GitHub
View package
NPM

Example#

<ActionButton icon={<Edit />}>Edit</ActionButton>

Content#

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

<ActionButton>Label only</ActionButton>
<ActionButton icon={<Edit />}>Icon + Label</ActionButton>
<ActionButton icon={<Edit />} aria-label="Icon only" />

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 icon={<Edit />} 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.
UNSAFE_classNamestring—
UNSAFE_styleCSSProperties—
autoFocusboolean—Whether the element should receive focus on render
Events
NameTypeDefaultDescription
onPress(e: PressEvent) => void—Called when the mouse or touch is released
onPressStart(e: PressEvent) => void—
onPressEnd(e: PressEvent) => void—
onPressChange(isPressed: boolean) => void—
onPressUp(e: PressEvent) => void—
onHover(e: HoverEvent) => void—
onHoverEnd(e: HoverEvent) => void—
onHoverChange(isHovering: boolean) => void—
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—
slotstring—
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 icon={<Edit />} aria-label="Edit" />

Disabled#

View guidelines

<ActionButton isDisabled>Action!</ActionButton>