An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
export const docs = {
name: 'useDragToSnapPoints',
displayName: 'useDragToSnapPoints',
keywords: [
'drag',
'snap',
'snap points',
'detents',
'drawer',
'flick',
'swipe',
'gesture',
],
params: [
{
name: 'ref',
type: 'RefObject<HTMLElement | null>',
description: 'A ref to the element a drag moves, along `axis` only.',
required: true,
},
{
name: 'options.axis',
type: "'x' | 'y'",
description:
'The axis the element moves along. A new one creates the drag again, starting where the element is.',
required: true,
},
{
name: 'options.snapPoints',
type: 'number[]',
description:
"Offsets in px along `axis` from the element's resting position, such as `[0, 240, 480]`, sorted before use (`onSettle` and `settleTo` count in that order); an empty list makes the drag do nothing. Unlike BottomSheet's `snapPoints`, they are not fractions of the viewport. New ones create the drag again and nothing more: the element stays where it is, a settle in flight included, and the next drag or `settleTo` starts there.",
required: true,
},
{
name: 'options.flickThreshold',
type: 'number',
description:
"A release faster than this, in px/s, carries to the next snap point in its direction. The default is the flick speed measured for UIKit's sheet. A new one creates the drag again, as new snap points do.",
default: '1008',
required: false,
},
{
name: 'options.onSettle',
type: '(index: number) => void',
description:
"Called with the snap point's index once the element settles on it. The latest function is the one called, so it may be new on every render.",
required: true,
},
],
returns: [
{
name: 'settleTo',
type: '(index: number) => void',
description:
'Settles the element on the snap point at `index` without a drag: the keyboard path. The same function on every render.',
},
],
usage: {
description:
"Lets a drag move an element along one axis and settles it on snap points when the finger lifts, the way an iOS sheet settles on its detents: on the nearest snap point to where it is, on the next one in its direction after a quick flick, and back where it started when the finger was moving back. The settle continues the release's velocity. For a bottom sheet, use BottomSheet's `snapPoints`; for a scrolling row, Carousel's `hasSnap`. Outside React, use `createDragToSnapPoints`.",
bestPractices: [
{
guidance: true,
description:
'Offer the same positions without a drag: buttons or keys that call `settleTo`.',
},
{
guidance: true,
description:
'Keep the settled index in state from `onSettle`, and render what the position means from it.',
},
{
guidance: false,
description:
'Use it for a sheet or a carousel: their own props already settle the way people expect.',
},
],
accessibility: [
{
name: 'Keyboard and assistive technology',
category: 'Keyboard',
description:
'A drag is one way in, never the only one. Give each snap point a control a keyboard and a screen reader can reach, such as Expand and Collapse buttons, and call `settleTo` from it. When a position changes what the element shows, announce the change.',
},
{
name: 'Reduce Motion',
category: 'Content',
criterion: '2.3.3 Animation from Interactions',
description:
'When the person asks for reduced motion, the settle after a touch drag becomes a short cross-fade into the snap point, as does any settle on a device whose primary pointer is coarse, such as a tablet; after a mouse or pen drag elsewhere it lands at once. `settleTo` fades on such a device and lands at once with a fine primary pointer. While the finger is down, the element still follows it.',
},
],
},
relatedComponents: ['BottomSheet', 'Carousel'],
relatedHooks: ['usePanGesture', 'useAnimator'],
importPath: '@astryxdesign/core/hooks',
category: 'interaction',
};
/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
export const docsDense = {
description:
'A drag that settles the element at ref on snap points (px offsets): {settleTo}.',
paramDescriptions: {
ref: 'Ref to the dragged element.',
'options.axis': "'x' or 'y'.",
'options.snapPoints': 'Ascending px offsets from the resting position.',
'options.flickThreshold':
'px/s past which a release carries one snap point; 1008.',
'options.onSettle': '(index) once settled; latest one is called.',
},
returnDescriptions: {
settleTo: '(index) settles without a drag; stable.',
},
usage: {
description:
'Nearest snap point, the next on a flick, the start when moving back; the settle keeps the release velocity. Sheets and carousels: use their props.',
bestPractices: [
{guidance: true, description: 'Wire settleTo to buttons and keys.'},
{guidance: false, description: 'Rebuild a sheet or carousel with it.'},
],
},
};