@atlaskit/primitives/constellation/pressable/usage.mdx

Primitives are token-backed low-level building blocks.

---
title: Pressable
description: A pressable is a primitive for building custom buttons.
order: 2
---

import pressablePrimaryDo from './images/pressable-01a-do.png';
import pressablePrimaryDont from './images/pressable-01b-dont.png';

## Usage

Use pressable to make custom-styled buttons and other pressable elements. Pressable works similarly
to an HTML `<button>`, but with Atlassian focus styles, analytics events, and styling APIs built in.

For example, you could use pressable to make a colored square button that opens a color picker, or a
basic card that shows more details when selected.

![Pressable anatomy](./images/pressable-anatomy.png)

1. **Pressable area:** For accessibility this should be a minimum of 24 by 24 pixels, unless exempt
   from
   [Target Size (Minimum) (Level AA)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html).
2. **Focus ring**: This is included in pressable and appears on keyboard focus.
3. **Accessible label:** Pressable should always include a clear label for accessibility. Use this
   to communicate the action that occurs when the button is pressed.

### Use existing buttons and other components whenever possible

Only use pressable when existing components such as [buttons](/components/button/examples) or
[menus](/components/menu/examples) can't be customized to fit your case.

Using [existing components](/components) with safe customizations is usually faster and keeps
Atlassian UI more visually consistent as things change.

<DoDont
	type="do"
	image={{
		url: pressablePrimaryDo,
		alt: 'A set of custom buttons built with pressable that are not possible using existing design system components',
	}}
>
	Use pressable to create buttons when there isn't an existing design system component to achieve
	your use case.
</DoDont>

<DoDont
	type="dont"
	image={{
		url: pressablePrimaryDont,
		alt: 'A custom button build with Pressable that looks similar to Button, an existing design system component',
	}}
>
	Don't use pressable to redesign elements that already exists in the Atlassian design system, such
	as <a href="/components/button/examples">buttons</a>. This can cause visual and behavioral
	inconsistency in products.
</DoDont>

## Accessibility

### Use clear labels for assistive technology

Pressable elements should always announce what action will happen once pressed, especially for
elements with no visible label, such as icon buttons.

![Pressable labels](./images/pressable-labels.png)

Use [the visually hidden component](/components/visually-hidden/examples) to provide an accessible
label. This will render hidden text inside the button, which is preferable over the `aria-label`
attribute because not all screen readers translate this between languages.

Also consider [a tooltip](/components/tooltip/examples) to provide sighted users with the same
information.

### Focus ring behavior

Pressable buttons are available in focus order, and include a visual ring to clarify what is in
focus by default. Adding additional focus styles is unnecessary.

### Avoid disabling buttons

Disabled buttons can cause accessibility problems. Avoid disabling buttons and
[follow our disabled button and tooltip guidance](/components/button/usage#avoid-disabling-buttons).

## Best practices

### Make it clear what can be pressed

Custom buttons should look interactive. Make sure clickable elements are clearly identifiable
through styles, surrounding context, labels, and other cues.

### Use pressable for on-page actions, not navigation

Pressable is meant for on-page actions such as opening modals or submitting forms. If you're making
something that navigates to a new page, use a component that renders a semantically correct HTML
`<a>` element such as:

- The [link](/components/primitives/link/examples) component for standard text links.
- The [anchor](/components/primitives/anchor/examples) primitive to create custom links.

Also, don't add underlines to a pressable. This makes the button appear to be a link, which can be
confusing for users who assume they can perform actions specific to links, such as opening links in
new windows.

## Content guidelines

### Use sentence case capitalization

Use sentence case capitalization, only capitalizing the first letter of the label and any proper
nouns. Other forms of capitalization should be only applied through styling with `text-transform`.

### Make it clear what pressing the button does

Make sure labels are concise, active, and clear about what pressing the button does.

For example, _Change issue color to yellow_ instead of _yellow_.

### Follow other label and UI content guidance

Follow label and content guidelines for [buttons](/components/button/usage#content-guidelines).
Review the [general UI text guidance](/foundations/accessibility/#meaningful-text) for specific
questions.

## Related

- Use existing components such as [buttons](/components/button/examples) or
  [menus](/components/menu/examples) for most actions in Atlassian products.
- Use the [anchor primitive for custom links](/components/primitives/button/usage).