Skip to main content
BETA
View Zag.js on Github
Join the Discord server

Pressable

Pressable handles press interactions across mouse, touch, keyboard, and screen readers.

Pressed 0 times

Long Pressed 0 times

Properties

Features

  • Handles mouse and touch events
  • Handles Enter or Space key presses
  • Handles screen reader virtual clicks
  • Uses pointer events where available, with fallbacks to mouse and touch events
  • Normalizes focus behavior on mouse and touch interactions across browsers
  • Handles disabling text selection on mobile while the press interaction is active
  • Normalizes many cross browser inconsistencies

Installation

To use the pressable machine in your project, run the following command in your command line:

npm install @zag-js/pressable @zag-js/react # or yarn add @zag-js/pressable @zag-js/react

This command will install the framework agnostic pressable logic and the reactive utilities for your framework of choice.

Usage

First, import the pressable package into your project

import * as pressable from "@zag-js/pressable"

The pressable package exports two key functions:

  • machine — The state machine logic for the pressable widget.
  • connect — The function that translates the machine's state to JSX attributes and event handlers.

You'll also need to provide a unique id to the useSetup hook. This is used to ensure that every pressable has a unique identifier. Next, import the required hooks and functions for your framework and use the pressable machine in your project 🔥

import * as pressable from "@zag-js/pressable" import { useMachine, normalizeProps } from "@zag-js/react" function Pressable() { const [state, send] = useMachine( pressable.machine({ id: "pressable", onPress() { console.log("press") }, onLongPress() { console.log("long press") }, }), ) const api = pressable.connect(state, send, normalizeProps) return ( <button {...api.pressableProps}> {api.isPressed ? "Pressed!" : "Press Me"} </button> ) }

Disabling the pressable

To make pressable disabled, set the context's disabled property to true

const [state, send] = useMachine( pressable.machine({ disabled: true, }), )

Methods and Properties

The pressable's api provides helpful properties and methods

PropertyDescription
isPressedWhether the target is currently pressed.
const api = connect(state, send) api.isPressed // false

Handlers

The pressable fires these handlers

PropertyDescription
onPressHandler that is called when the press is released over the target.
onPressStartHandler that is called when a press interaction starts.
onPressEndHandler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressUpHandler that is called when a press is released over the target, regardless of whether it started on the target or not.
onLongPressHandler that is called when the element has been pressed for 500 milliseconds

Each of these handlers is fired with a PressEvent, which exposes information about the target and the type of event that triggered the interaction.

PropertyDescriptionType
typeThe type of press event being fired.pressstart or pressend or pressup or press or longpress
pointerTypeThe pointer type that triggered the press event.PointerType
targetThe target element of the press event.HTMLElement
originalEventThe original fired eventPointerEvent

Styling guide

Pressed State

When the pressable element is pressed, the data-pressed attribute is added to the target

[data-pressed] { /* styles for pressable pressed state */ }

Disabled State

When the pressable element is disabled, the data-disabled attribute is added to the target

[data-disabled] { /* styles for pressable disabled state */ }

Edit this page on GitHub

On this page