use-hold-repeat

Repeats an action while a control is held down

Usage

use-hold-repeat calls a function once, then repeats it at a fixed or accelerating interval until it is stopped. The hook does not attach DOM events: call start and stop from your own handlers, or use use-hold-repeat-handlers to get them ready-made:

Count: 0

import { useState } from 'react';
import { Button, Stack, Text } from '@mantine/core';
import { useHoldRepeat } from '@mantine/hooks';

function Demo() {
  const [count, setCount] = useState(0);

  const { start, stop } = useHoldRepeat(() => setCount((c) => c + 1), {
    delay: 400,
    interval: (step) => Math.max(40, 300 - step * 20),
  });

  return (
    <Stack align="center">
      <Text fw={500}>Count: {count}</Text>
      <Button onPointerDown={start} onPointerUp={stop} onPointerLeave={stop}>
        Hold to increment
      </Button>
    </Stack>
  );
}

Definition

type UseHoldRepeatInterval = number | ((count: number) => number);

interface UseHoldRepeatOptions {
  /** Initial delay in ms before repeating begins after the first trigger.
   *  Repeat happens only when both `delay` and `interval` are set. */
  delay?: number;

  /** Interval in ms between repeats, or `(count) => ms` for dynamic/accelerating intervals.
   *  Repeat happens only when both `delay` and `interval` are set. */
  interval?: UseHoldRepeatInterval;

  /** Called once when a hold starts, before the first trigger */
  onStart?: () => void;

  /** Called once when a hold stops */
  onStop?: () => void;
}

interface UseHoldRepeatReturnValue {
  /** Fires the trigger once, then schedules repeats while held */
  start: () => void;

  /** Stops repeating and resets the internal step count */
  stop: () => void;
}

function useHoldRepeat(
  onTrigger: () => void,
  options?: UseHoldRepeatOptions,
): UseHoldRepeatReturnValue

Repeat is opt-in

By default, start calls the function once. To repeat it, set both delay and interval. delay is the pause before the first repeat, interval is the time between the following ones:

import { useHoldRepeat } from '@mantine/hooks';

function Demo() {
  // Fires once on start, then repeats every 100ms after a 500ms delay
  const { start, stop } = useHoldRepeat(() => console.log('tick'), {
    delay: 500,
    interval: 100,
  });

  return (
    <button onPointerDown={start} onPointerUp={stop} onPointerLeave={stop}>
      Hold me
    </button>
  );
}

Accelerating interval

Pass a function to interval to calculate the delay before each repeat from the number of calls made so far. count starts at 2: the first call is the immediate one, the second is the first repeat.

import { useHoldRepeat } from '@mantine/hooks';

function Demo() {
  const { start, stop } = useHoldRepeat(() => console.log('tick'), {
    delay: 500,
    // 300ms, then faster and faster down to a 50ms floor
    interval: (count) => Math.max(50, 300 - count * 10),
  });

  return (
    <button onPointerDown={start} onPointerUp={stop} onPointerLeave={stop}>
      Hold me
    </button>
  );
}

Cleanup

The timer is cleared automatically when the component unmounts.

Exported types

UseHoldRepeatInterval, UseHoldRepeatOptions and UseHoldRepeatReturnValue types are exported from the @mantine/hooks package:

import type {
  UseHoldRepeatInterval,
  UseHoldRepeatOptions,
  UseHoldRepeatReturnValue,
} from '@mantine/hooks';