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

Primitives are token-backed low-level building blocks.

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

import PressableDefault from '../../examples/constellation/pressable/default';
import PressableBasic from '../../examples/constellation/pressable/basic';
import PressableStyled from '../../examples/constellation/pressable/styled';
import PressableWithoutVisibleLabels from '../../examples/constellation/pressable/without-visible-labels';
import PressableDisabled from '../../examples/constellation/pressable/disabled';
import PressableHtmlAttributes from '../../examples/constellation/pressable/html-attributes';
import PressablePressTracing from '../../examples/constellation/pressable/press-tracing';
import PressableAnalytics from '../../examples/constellation/pressable/analytics';
import PressableAnalyticsGASv3 from '../../examples/constellation/pressable/analytics-gasv3';

import { CodeDocsHeader } from '@af/design-system-docs-ui';
import SectionMessage from '@atlaskit/section-message';

<CodeDocsHeader
	name="@atlaskit/primitives"
	repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
	directoryName="primitives"
/>

Pressable is a primitive for building custom buttons with Atlassian Design System styling and
built-in event tracking. It renders a `<button>` element. Use pressable when existing
[buttons](/components/button/examples) can't be customized to fit your needs.

## Default

Pressable is unstyled by default, aside from basic focus styles.

<Example Component={PressableDefault} packageName="@atlaskit/primitives/pressable" />

## Basic styling with XCSS

Pressable can be styled further using the design system styling API,
[XCSS](/components/primitives/xcss).

Make sure styling indicates the interaction state using `:hover` and `:active` pseudo-classes.

<Example Component={PressableBasic} packageName="@atlaskit/primitives/pressable" />

## Advanced styling

Use a combination of XCSS and other primitives for more complex designs.

<Example
	Component={PressableStyled}
	packageName="@atlaskit/primitives/pressable"
	backgroundColor="white"
/>

## Disabled

You can disable pressable buttons with the `isDisabled` prop. Disabled styles should be applied and
defined conditionally using XCSS.

Disabled buttons can cause accessibility issues (disabled elements are not in the tab order) so
wherever possible, avoid using `isDisabled`. Instead, use validation or other techniques to show
users how to proceed.

<!-- todo: snippet for disabled a11y warnings? -->

<Example Component={PressableDisabled} packageName="@atlaskit/primitives/pressable" />

## Buttons without visible labels

For buttons without visible labels such as icon buttons, make an accessible label available using
the [visually hidden component](/components/visually-hidden/examples). This renders hidden text
inside the button for assistive technologies, which is preferable to an `aria-label` attribute
because not all screen readers translate these between languages.

Also, consider providing a [tooltip](/components/tooltip) to help sighted users understand the
button's purpose.

<Example
	Component={PressableWithoutVisibleLabels}
	packageName="@atlaskit/primitives/pressable"
	backgroundColor="white"
/>

## HTML attributes

Pressable passes all valid HTML attributes to the underlying `<button>` element. The `type`
attribute defaults to `button` to prevent unintentionally submitting forms.

<Example Component={PressableHtmlAttributes} packageName="@atlaskit/primitives/pressable" />

<Snippet name="primitives-event-tracking-header" variables={{ componentName: 'pressable' }} />

<Example Component={PressableAnalytics} packageName="@atlaskit/primitives/pressable" />

<Snippet name="primitives-event-tracking-gasv3" />

<Example Component={PressableAnalyticsGASv3} packageName="@atlaskit/primitives/pressable" />

<Snippet name="primitives-event-tracking-ufo" variables={{ componentName: 'pressable' }} />

<Example Component={PressablePressTracing} packageName="@atlaskit/primitives/pressable" />