# useHoldRepeat
Package: @mantine/hooks
Import: import { useHoldRepeat } from '@mantine/hooks';

## 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](https://alpha.mantine.dev/llms/hooks-use-hold-repeat-handlers.md) to get them ready-made:

```tsx
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

```tsx
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:

```tsx
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.

```tsx
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:

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