useDrag

Feature-rich Drag element hook

Components that use this hook: <SlideAction>, <Dialog> mobile variant

Import

import {useDrag} from '@kaiverse/k/hooks'

Basic

Playground

Drag the block below

😀

ResetReset with transition

Source code

basic.tsx

import {useDrag} from '@kaiverse/k/hooks'

export default function UseDragBasic() {
  const {targetRef: draggableTargetRef, setPosition} = useDrag<HTMLDivElement>()

  return (
    <>
      Drag the block below
      <div className="playground p-4 h-[30vh]">
        <div
          ref={draggableTargetRef}
          className="rounded-lg inline-block border-2 border-accent p-4 bg-accent/20 cursor-move select-none group"
        >
          <div className="group-active:animate-none animate-bounce">😀</div>
        </div>
      </div>
      <div className="mt-4 flex items-center gap-4">
        <button
          className="btn btn-neutral btn-outline"
          type="button"
          onClick={() => setPosition({x: 0, y: 0})}
        >
          Reset
        </button>

        <button
          className="btn btn-neutral"
          type="button"
          onClick={() => setPosition({x: 0, y: 0}, {transition: true})}
        >
          Reset with transition
        </button>
      </div>
    </>
  )
}

Direction

Available options: 'vertical', 'horizontal', 'both'.
Default: 'both'.

Horizontal only

Vertical only

Reset

direction.tsx

useDrag({direction: ...})

Step

Move the target element by a fixed amount of pixels. The stepSize option can be a number for both directions or an object {x: number, y: number}.

With {"stepSize":50}

Drag the block below

😀

Reset

stepSize.tsx

useDrag({stepSize: ...})

Limit

Limit the draggable area by using the limit or relativeLimit option.

Note

The limit area is calculated based on the target element’s top-left corner.

Drag the block below

limitBoxSize: {"width":"300px","height":"150px"}
targetSize: {"width":"100px","height":"50px"}
limit: {"x":{"min":0,"max":200},"y":{"min":0,"max":100}}

Limit box

👋 drag me

limit.tsx

useDrag({
  limit: {...}
})

Relative Limit

You can limit the dragging area relative to the direct parent element by using the relativeLimit option. This option will be ignored if limit is provided.

Note

relativeLimit doesn’t observe the parent element’s size changes, you will need to use limit and update it manually (eg: via Resize Observer API).

Limit the dragging distance by:

• "client-size" recommended : parent element’s client size (includes padding but excludes borders, margins).
  DO NOT use this option when parent is an inline element.
• "client-no-padding" recommended : same as "client-size" but excludes padding.
• "offset-size": parent element’s offset size (including borders, padding).
• "offset-no-padding": same as "offset-size" but excludes padding.

Confused? Let’s put it another way:

Options	Description
"client-*"	Normal limit the dragging area.
"offset-*"	Ignore parent border-width - can be dragged over parent’s border area.
"*-no-padding"	Ignore the parent padding area - can be dragged over it.

Playground

Try to drag the block below

👋 drag me

Playground related styles:
{
  "padding": "2rem",
  "borderWidth": "16px"
}

: Border

relative-limit.tsx

useDrag({
  relativeLimit: '...',
})

decelerationEffect

Allow dragging over the limit, and enable deceleration effect. After releasing (pointercancel or pointerup event), the target element will move back to the nearest limit position.

Note

decelerationEffect only available when limit or relativeLimit is provided.

Try dragging the element over the limit area.

limitBoxSize: {"width":"300px","height":"150px"}
targetSize: {"width":"100px","height":"50px"}
limit: {"x":{"min":0,"max":200},"y":{"min":0,"max":100}}

Limit box

👋 drag me

deceleration-effect.tsx

useDrag({
  decelerationEffect: true,
})

Special Types

Name	Type	Description
UseDragPosition	{x: number; y: number}	Position parameters
UseDragSetPosition	{position: UseDragPosition, options?: ...} options type: See setPosition Options section	Update position.
UseDragRelativeLimit	"client-size" | "client-no-padding" | "offset-size" | "offset-no-padding"	relativeLimit options.
UseDragOptions	See useDrag Options below	All useDrag options.

setPosition Options

Name	Type	Default	Description
transition	string | true	—	CSS transition for the position change. See transition section for more info.
skipCalulateStep	boolean	false	If stepSize > 0 and you wanna manually update the position, consider set this option to true to skip the default calculation.
shouldUpdatePositionState	boolean	false	Enable this flag to allow updating the returned position state and manually handle the transform animation, please note that your component will be re-rendered. By default, the hook will handle the calculation for you, and your component won’t re-render.

transition

Apply the transition to the target element once, for that specific position update - setPosition only.

Note

This hook will transform the target element by using CSS translate if the browser supports it, otherwise transform.
Default transition: {translate | transform} 500ms cubic-bezier(0.32, 0.72, 0, 1).

If you set transition to true, it will apply the default transition. You can also provide a custom transition style by passing a string value.

useDrag Options

Name	Type	Default	Description
targetRef	RefObject<T>	—	If provided, this hook will track and make this ref element draggable instead of its own internal target ref (and also won’t return it anymore).
direction	'vertical' | 'horizontal' | 'both'	'both'	Dragging direction.
limit	{x?: {max?: number; min?: number}, y?: {max?: number; min?: number}}	—	Limit the draggable area. See Limit section.
relativeLimit	UseDragRelativeLimit	—	Limit dragging distance relatively to the direct parent element. Will be ignored if limit is provided. See Relative Limit section.
decelerationEffect	boolean	false	Allow dragging over the limit, and enable deceleration effect. After releasing (pointercancel or pointerup event), the target element will move back to the nearest limit position. Only available when limit or relativeLimit is provided.
stepSize	number | UseDragPosition	0	Position step size.
addBrowserHintStyles	boolean	true	By default, the hook will add will-change: transform and touch-action: none to the target element.
onStart	(target: RefObject<T>, position: UseDragPosition, setPosition: UseDragSetPosition) => void	—	Callback when dragging starts.
onMove	(target: RefObject<T>, position: UseDragPosition) => void	—	Callback when dragging.
onEnd	(target: RefObject<T>, position: UseDragPosition, setPosition: UseDragSetPosition) => void	—	Callback when dragging ends.
ignorePointerCancel	boolean	false	If true, ignore the pointercancel event.
touch	boolean	true	Should listening touch events or not. Side note: This hook treats pointer events caused by a pen or stylus device (pointerType === 'pen') same as touch events.
mouse	boolean	true	Should listening mouse’s main button events (usually left-click) or not.
disabled	boolean	false	If true, the target element won’t draggable anymore. Equivalent to touch === false && mouse === false

Footgun Flags

Easier to shoot yourself in the foot with these options.

Name	Type	Default	Description
manualStylingOnMove	boolean	false	Set to true to allow update position state onMove and manually handle styling such as CSS transform. Note: Your component will re-render on every step move.
returnedPositionDebounceTime	number	0	Enable debouncing for the setPosition setter in millisecond (ms). Used for manually handling the moving transform animation (manualStylingOnMove = true) by using returned position state instead of the onMove event. It doesn’t affect the default onMove transform animation (manualStylingOnMove = false).