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.

install	`yarn add @react-spectrum/button`
version	3.0.0-rc.2
usage	`import {ActionButton} from '@react-spectrum/button'`

View guidelines

Spectrum

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#

Name	Type	Default	Description
`isQuiet`	`boolean`	—	Whether the ActionButton should be displayed with a quiet style.
`isSelected`	`boolean`	—	Whether the ActionButton should be displayed with a selected state.
`isEmphasized`	`boolean`	—	Whether the ActionButton should be displayed with a emphasized style.
`holdAffordance`	`boolean`	—	Whether the ActionButton should be displayed with a hold icon.
`isDisabled`	`boolean`	—	Whether the button is disabled
`elementType`	`string \| JSXElementConstructor<any>`	`"button"`	The HTML element or React element used to render the button, e.g. "div", "a", or `RouterLink`.
`children`	`ReactNode`	—	The content to display in the button.
`href`	`string`	—	A URL to link to if elementType="a".
`target`	`string`	—	The target window for the link.
`UNSAFE_className`	`string`	—
`UNSAFE_style`	`CSSProperties`	—
`autoFocus`	`boolean`	—	Whether the element should receive focus on render

Events

Name	Type	Default	Description
`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`	—
`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

Name	Type	Default	Description
`flex`	`string \| number \| boolean`	—
`flexGrow`	`number`	—
`flexShrink`	`number`	—
`flexBasis`	`number \| 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'`	—
`flexOrder`	`number`	—
`gridArea`	`string`	—
`gridColumn`	`string`	—
`gridRow`	`string`	—
`gridColumnStart`	`string`	—
`gridColumnEnd`	`string`	—
`gridRowStart`	`string`	—
`gridRowEnd`	`string`	—

Spacing

Name	Type	Default	Description
`margin`	`DimensionValue`	—
`marginTop`	`DimensionValue`	—
`marginLeft`	`DimensionValue`	—
`marginRight`	`DimensionValue`	—
`marginBottom`	`DimensionValue`	—
`marginStart`	`DimensionValue`	—
`marginEnd`	`DimensionValue`	—
`marginX`	`DimensionValue`	—
`marginY`	`DimensionValue`	—

Sizing

Name	Type	Default	Description
`width`	`DimensionValue`	—
`minWidth`	`DimensionValue`	—
`maxWidth`	`DimensionValue`	—
`height`	`DimensionValue`	—
`minHeight`	`DimensionValue`	—
`maxHeight`	`DimensionValue`	—

Positioning

Name	Type	Default	Description
`position`	`'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky'`	—
`top`	`DimensionValue`	—
`bottom`	`DimensionValue`	—
`left`	`DimensionValue`	—
`right`	`DimensionValue`	—
`start`	`DimensionValue`	—
`end`	`DimensionValue`	—
`zIndex`	`number`	—
`isHidden`	`boolean`	—

Accessibility

Name	Type	Default	Description
`role`	`string`	—
`id`	`string`	—
`tabIndex`	`number`	—
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-owns`	`string`	—	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-hidden`	`boolean \| 'false' \| 'true'`	—	Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

'size-0'
  | 'size-10'
  | 'size-25'
  | 'size-40'
  | 'size-50'
  | 'size-65'
  | 'size-75'
  | 'size-85'
  | 'size-100'
  | 'size-115'
  | 'size-125'
  | 'size-130'
  | 'size-150'
  | 'size-160'
  | 'size-175'
  | 'size-200'
  | 'size-225'
  | 'size-250'
  | 'size-300'
  | 'size-350'
  | 'size-400'
  | 'size-450'
  | 'size-500'
  | 'size-550'
  | 'size-600'
  | 'size-675'
  | 'size-700'
  | 'size-800'
  | 'size-900'
  | 'size-1000'
  | 'size-1200'
  | 'size-1250'
  | 'size-1600'
  | 'size-1700'
  | 'size-2000'
  | 'size-2400'
  | 'size-3000'
  | 'size-3400'
  | 'size-3600'
  | 'size-4600'
  | 'size-5000'
  | 'size-6000'
  | 'static-size-0'
  | 'static-size-10'
  | 'static-size-25'
  | 'static-size-50'
  | 'static-size-40'
  | 'static-size-65'
  | 'static-size-100'
  | 'static-size-115'
  | 'static-size-125'
  | 'static-size-150'
  | 'static-size-175'
  | 'static-size-200'
  | 'static-size-225'
  | 'static-size-250'
  | 'static-size-300'
  | 'static-size-400'
  | 'static-size-450'
  | 'static-size-500'
  | 'static-size-550'
  | 'static-size-600'
  | 'static-size-700'
  | 'static-size-800'
  | 'static-size-900'
  | 'static-size-1000'
  | 'static-size-1200'
  | 'static-size-1700'
  | 'static-size-2400'
  | 'static-size-2600'
  | 'static-size-3400'
  | 'static-size-3600'
  | 'static-size-4600'
  | 'static-size-5000'
  | 'static-size-6000'
  | 'single-line-height'
  | 'single-line-width'
  | string
  | number

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`
`pointerType`	`PointerType`
`target`	`HTMLElement`
`shiftKey`	`boolean`
`ctrlKey`	`boolean`
`metaKey`	`boolean`

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

ReactFocusEvent<any> & {stopPropagation: () => void,
continuePropagation: () => void
}

ReactKeyboardEvent<any> & {stopPropagation: () => void,
continuePropagation: () => void
}

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>