Svelte Interactions

At surface level, interactions may seem like a simple concept, but once you start peeling back the onion they are quite complex. For something as simple as a button to behave properly across all browsers and devices, you need more than just a click event handler.

If you aren't convinced, it's highly recommended to read this three-part blog post, which goes into detail about the complexities of interactions.

This project is heavily inspired by that article and contains a ton of code derived from React Aria's Interactions packages. It aims to provide a similar API for Svelte, in the form of Svelte Actions and eventually spreadable event attributes (once Svelte 5 is released).

While this project is still in its infancy, it'll be documented here. It will eventually get a dedicated website, but for now this will have to do.

Installation

npm install svelte-interactions

Press Interaction

The press interaction is used to implement buttons, links, and other pressable elements. It handles mouse, touch, and keyboard interactions, and ensures that the element is accessible to screen readers and keyboard users.

No more having to wrangle all those event handlers yourself! Just and use the press action along with the different PressEvents to provide a consistent experience across all browsers and devices.

Basic Usage

<script lang="ts">
	import { createPress } from 'svelte-interactions';

	const { pressAction } = createPress();
</script>

<button
	use:pressAction
	on:press={(e) => {
		console.log('you just pressed a button!', e);
	}}
>
	Press Me
</button>

createPress

Creates a new press interaction instance. Each element should have its own instance, as it maintains state for a single element. For example, if you had multiple buttons on a page:

<script lang="ts">
	import { createPress } from 'svelte-interactions';

	const { pressAction: pressOne } = createPress();
	const { pressAction: pressTwo } = createPress();
</script>

<button use:pressOne on:press> Button One </button>
<button use:pressTwo on:press> Button Two </button>

PressConfig

createPress takes in an optional PressConfig object, which can be used to customize the interaction.

import { createPress } from 'svelte-interactions';

const { pressAction } = createPress({ isDisabled: true });

type PressConfig = PressHandlers {
	/**
	 * Whether the target is in a controlled press state
	 * (e.g. an overlay it triggers is open).
	 *
	 * @default false
	 */
	isPressed?: boolean;

	/**
	 * Whether the press events should be disabled.
	 *
	 * @default false
	 */
	isDisabled?: boolean;

	/**
	 * Whether the target should not receive focus on press.
	 *
	 * @default false
	 */
	preventFocusOnPress?: boolean;

	/**
	 * Whether press events should be canceled when the pointer
	 * leaves the target while pressed. By default, this is
	 * `false`, which means if the pointer returns back over
	 * the target while pressed, `pressstart`/`onPressStart`
	 * will be fired again. If set to `true`, the press is
	 * canceled when the pointer leaves the target and
	 * `pressstart`/`onPressStart` will not be fired if the
	 * pointer returns.
	 *
	 * @default false
	 */
	shouldCancelOnPointerExit?: boolean;

	/**
	 * Whether text selection should be enabled on the pressable element.
	 */
	allowTextSelectionOnPress?: boolean;
};

The PressConfig object also includes handlers for all the different PressHandlers. These are provided as a convenience, should you prefer to handle the events here rather than the custom on:press* events dispatched by the element with the pressAction.

Be aware that event if you use these handlers, the custom on:press* events for whatever handlers you use will not be dispatched to the element. We only dispatch the events that aren't handled by the PressHandlers.

type PressHandlers = {
	/**
	 * Handler called when the press is released over the target.
	 */
	onPress?: (e: PressEvent) => void;

	/**
	 * Handler called when a press interaction starts.
	 */
	onPressStart?: (e: PressEvent) => void;

	/**
	 * Handler called when a press interaction ends, either over
	 * the target or when the pointer leaves the target.
	 */
	onPressEnd?: (e: PressEvent) => void;

	/**
	 * Handler called when the press state changes.
	 */
	onPressChange?: (isPressed: boolean) => void;

	/**
	 * Handler called when a press is released over the target,
	 * regardless of whether it started on the target or not.
	 */
	onPressUp?: (e: PressEvent) => void;
};

PressResult

The createPress function returns a PressResult object, which contains the pressAction action, and the isPressed state. More returned properties may be added in the future if needed.

type PressResult = {
	/** Whether the target is currently pressed. */
	isPressed: Readable<boolean>;
	/** A Svelte Action which handles applying the event listeners to the element. */
	pressAction: (node: HTMLElement | SVGElement) => PressActionReturn;
};

Custom Events

When you apply the pressAction to an element, it will dispatch custom on:press* events. You can use these or the PressHandlers to handle the various press events.

type PressActionReturn = ActionReturn<
	undefined,
	{
		/**
		 * Dispatched when the press is released over the target.
		 */
		'on:press'?: (e: CustomEvent<PressEvent>) => void;

		/**
		 * Dispatched when a press interaction starts.
		 */
		'on:pressstart'?: (e: CustomEvent<PressEvent>) => void;

		/**
		 * Dispatched when a press interaction ends, either over
		 * the target or when the pointer leaves the target.
		 */
		'on:pressend'?: (e: CustomEvent<PressEvent>) => void;

		/**
		 * Dispatched when a press is released over the target,
		 * regardless of whether it started on the target or not.
		 */
		'on:pressup'?: (e: CustomEvent<PressEvent>) => void;
	}
>;

PressEvent

This is the event object dispatched by the custom on:press* events, and is also passed to the PressHandlers should you choose to use them.

type PointerType = 'mouse' | 'pen' | 'touch' | 'keyboard' | 'virtual';

interface PressEvent {
	/** The type of press event being fired. */
	type: 'pressstart' | 'pressend' | 'pressup' | 'press';

	/** The pointer type that triggered the press event. */
	pointerType: PointerType;

	/** The target element of the press event. */
	target: Element;

	/** Whether the shift keyboard modifier was held during the press event. */
	shiftKey: boolean;

	/** Whether the ctrl keyboard modifier was held during the press event. */
	ctrlKey: boolean;

	/** Whether the meta keyboard modifier was held during the press event. */
	metaKey: boolean;

	/** Whether the alt keyboard modifier was held during the press event. */
	altKey: boolean;

	/**
	 * By default, press events stop propagation to parent elements.
	 * In cases where a handler decides not to handle a specific event,
	 * it can call `continuePropagation()` to allow a parent to handle it.
	 */
	continuePropagation(): void;
}

Long Press Interaction

The hover interaction provides an API for consistent long press behavior across all browsers and devices, with support for a custom time threshold and accessible description.

Basic Usage

<script lang="ts">
	import { createLongPress } from 'svelte-interactions';

	const { longPressAction } = createLongPress();
</script>

<button
	use:longPressAction
	on:longpress={(e) => {
		console.log('you just long pressed a button!', e);
	}}
>
	Long Press Me
</button>

createLongPress

Creates a new longpress interaction instance. Each element should have its own instance, as it maintains state for a single element. For example, if you had multiple buttons on a page:

<script lang="ts">
	import { createLongPress } from 'svelte-interactions';

	const { longPressAction: longPressOne } = createLongPress();
	const { longPressAction: longPressTwo } = createLongPress();
</script>

<button use:longPressOne on:longpress> Button One </button>
<button use:longPressTwo on:longpress> Button Two </button>

LongPressConfig

createLongPress takes in an optional LongPressConfig object, which can be used to customize the interaction.

import { createLongPress } from 'svelte-interactions';

const { pressLongAction } = createPress({ isDisabled: true, threshold: 1000 });

type LongPressConfig = LongPressHandlers & {
	/**
	 * Whether the long press events should be disabled
	 */
	isDisabled?: boolean;

	/**
	 * The amount of time (in milliseconds) to wait before
	 * triggering a long press event.
	 */
	threshold?: number;

	/**
	 * A description for assistive techology users indicating that a
	 * long press action is available, e.g. "Long press to open menu".
	 */
	accessibilityDescription?: string;
};

The LongPressConfig object also includes handlers for all the different LongPressHandlers. These are provided as a convenience, should you prefer to handle the events here rather than the custom on:longpress* events dispatched by the element with the longPressAction.

Be aware that event if you use these handlers, the custom on:longpress* events for whatever handlers you use will not be dispatched to the element. We only dispatch the events that aren't handled by the LongPressHandlers.

export type LongPressHandlers = {
	/**
	 * Handler that is called when a long press interaction starts.
	 */
	onLongPressStart?: (e: LongPressEvent) => void;

	/**
	 * Handler that is called when a long press interaction ends, either
	 * over the target or when the pointer leaves the target.
	 */
	onLongPressEnd?: (e: LongPressEvent) => void;

	/**
	 * Handler that is called when the threshold time is met while
	 * the press is over the target.
	 */
	onLongPress?: (e: LongPressEvent) => void;
};

LongPressResult

The createLongPress function returns a LongPressResult object, which contains the longPressAction action, and the description state. More returned properties may be added in the future if needed.

type LongPressResult = {
	/**
	 * A Svelte action which handles applying the event listeners
	 * and dispatching events to the element
	 */
	longPressAction: (node: HTMLElement | SVGElement) => LongPressActionReturn;

	/**
	 * A writable store to manage the accessible description for the long
	 * press action. It's initially populated with the value passed to the
	 * `accessibilityDescription` config option, but can be updated at any
	 * time by calling `description.set()`, and the new description will
	 * reflect in the DOM.
	 */
	accessibilityDescription: Writable<string | undefined>;
};

Custom Events

When you apply the longPressAction to an element, it will dispatch custom on:longpress* events for events you aren't handling via the LongPressConfig props. You can use these or the LongPressHandlers to handle the various longpress events.

type LongPressActionReturn = ActionReturn<
	undefined,
	{
		/**
		 * Dispatched when the threshold time is met while
		 * the press is over the target.
		 */
		'on:longpress'?: (e: CustomEvent<LongPressEvent>) => void;

		/**
		 * Dispatched when a long press interaction starts.
		 */
		'on:longpressstart'?: (e: CustomEvent<LongPressEvent>) => void;

		/**
		 * Dispatched when a long press interaction ends, either
		 * over the target or when the pointer leaves the target.
		 */
		'on:longpressend'?: (e: CustomEvent<LongPressEvent>) => void;
	}
>;

PressEvent

This is the event object dispatched by the custom on:press* events, and is also passed to the PressHandlers should you choose to use them.

type PointerType = 'mouse' | 'pen' | 'touch' | 'keyboard' | 'virtual';

interface PressEvent {
	/** The type of longpress event being fired. */
	type: 'longpressstart' | 'longpressend' | 'longpress';

	/** The pointer type that triggered the press event. */
	pointerType: PointerType;

	/** The target element of the press event. */
	target: Element;

	/** Whether the shift keyboard modifier was held during the press event. */
	shiftKey: boolean;

	/** Whether the ctrl keyboard modifier was held during the press event. */
	ctrlKey: boolean;

	/** Whether the meta keyboard modifier was held during the press event. */
	metaKey: boolean;

	/** Whether the alt keyboard modifier was held during the press event. */
	altKey: boolean;
}

Hover Interaction

The hover interaction provides an API for consistent hover behavior across all browsers and devices, ignoring emulated mouse events on touch devices.

Basic Usage

<script lang="ts">
	import { createHover } from 'svelte-interactions';

	const { hoverAction } = createHover();
</script>

<button
	use:hoverAction
	on:hoverstart={(e) => {
		console.log('you just hovered me!', e);
	}}
	on:hoverstart={(e) => {
		console.log('you just unhovered me!', e);
	}}
>
	Press Me
</button>

createHover

Creates a new hover interaction instance. Each element should have its own instance, as it maintains state for a single element. For example, if you had multiple elements you wanted to apply hover state to on a page:

<script lang="ts">
	import { createPress } from 'svelte-interactions';

	const { hoverAction: hoverOne } = createHover();
	const { hoverAction: hoverTwo } = createHover();
</script>

<div use:hoverOne on:hoverstart>Hoverable element one</div>
<div use:hoverTwo on:hoverstart>Hoverable element two</div>

HoverConfig

The createHover function takes in an optional HoverConfig object, which can be used to customize the interaction.

import { createHover } from 'svelte-interactions';

const { hoverAction } = createHover({ isDisabled: true });

type HoverConfig = HoverHandlers & {
	/**
	 * Whether the hover events should be disabled
	 */
	isDisabled?: boolean;
};

The HoverConfig object also includes handlers for all the different HoverHandlers. These are provided as a convenience, should you prefer to handle the events here rather than the custom on:hover* events dispatched by the element with the hoverAction.

Be aware that event if you use these handlers, the custom on:hover* events for whatever handlers you use will not be dispatched to the element. We only dispatch the events that aren't handled by the HoverHandlers.

type HoverHandlers = {
	/**
	 * Handler called when a hover interaction starts.
	 */
	onHoverStart?: (e: HoverEvent) => void;

	/**
	 * Handler called when a hover interaction ends.
	 */
	onHoverEnd?: (e: HoverEvent) => void;

	/**
	 * Handler called when the hover state changes.
	 */
	onHoverChange?: (isHovering: boolean) => void;
};

HoverResult

The createHover function returns a HoverResult object, which contains the hoverAction action, and the isHovering state. More returned properties may be added in the future if needed.

export type HoverResult = {
	/**
	 * Whether the element is currently being hovered
	 */
	isHovered: Readable<boolean>;

	/**
	 * A Svelte action which handles applying the event listeners
	 * to the element and dispatching the custom `on:hover*` events.
	 */
	hoverAction: (node: HTMLElement | SVGElement) => HoverActionReturn;
};

Custom Events

When you apply the hoverAction to an element, it will dispatch custom on:hover* events. You can use these or the HoverHandlers to handle the various hover events.

type HoverActionReturn = ActionReturn<
	undefined,
	{
		/**
		 * Dispatched when a hover interaction starts.
		 */
		'on:hoverstart'?: (e: CustomEvent<HoverEvent>) => void;

		/**
		 * Dispatched when a hover interaction ends.
		 */
		'on:hoverend'?: (e: CustomEvent<HoverEvent>) => void;
	}
>;

HoverEvent

This is the event object dispatched by the custom on:hover* events, and is also passed to the HoverHandlers should you choose to use them.

interface HoverEvent {
	/** The type of hover event being fired. */
	type: 'hoverstart' | 'hoverend';
	/** The pointer type that triggered the hover event. */
	pointerType: 'mouse' | 'pen';
	/** The target element of the hover event. */
	target: Element;
}