@solid-primitives/idle

createIdleTimer - A primitive to track the user's idle status and take appropriate action.

Installation

npm install @solid-primitives/idle
# or
yarn add @solid-primitives/idle
# or
pnpm add @solid-primitives/idle

How to use it

createIdleTimer provides different accessors and methods to observe the user's idle status and react to its changing.

Basic example

const App: Component = () => {
  const { isIdle, isPrompted, reset } = createIdleTimer({
    onIdle: logout,
    idleTimeout: 300_000,
    promptTimeout: 60_000,
  });
  return (
    <Switch fallback={<ClientPage />}>
      <Match when={isIdle()}>
        <LoggedOut />
      </Match>
      <Match when={isPrompted()}>
        <PromptPopup onConfirm={reset /*or stop*/} />
      </Match>
    </Switch>
  );
};

Accessors and methods

To interact with the timers, createIdleTimer provides:

• isIdle and isPrompted: Accessor<boolean>; these two accessors report the user status. They do not concur.
• start, stop and reset: () => void; allow rispectively to start and stop the timers, and to reset them. start and reset, create a custom manualstart and manualreset event, that will be passed to the onIdle and onPrompt callbacks if no oher activity occurs (there's another custom event, mount, created when timers start automatically). Finally stop and reset don't trigger onActive.
• triggerIdle: () => void; manually sets isIdle to true, and triggers the onIdle callback, passing a custom manualidle event. It doesn't trigger onActive or onPrompt.

Configuration options

createIdleTimer takes as an optional argument an object with the timer's configuration options. Each key has a default value. The options are:

• idleTimeout: number; time of user's inactivity in milliseconds before the idle status changes to idle. This time is extended by the promptTimeout option. It defaults to 15 minutes.
• promptTimeout: number; to meet the typical usecase when we want to prompt the user to check if we they are still active, an additional timer starts running right after the idleTimeout expires. In this time slot, the user is in the prompt phase, whose duration is decided by promptTimout. It defaults to 0.
• onIdle: (evt: Event) => void; callback triggered when the user status passes to idle. When invoked, the last event fired before the prompt phase will be passed as parameter. Events fired in the prompt phase will not count. It defaults to an empty function.
• onPrompt: (evt: Event) => void; when the idleTimeout expires, before declaring the idle status, onPrompt callback is fired, starting the prompt timer. When invoked, the last event fired before the prompt phase will be passed as a parameter. It defaults to an empty function.
• onActive: (evt: Event) => void; callback called when the user resumes activity after having been idle (resuming from prompt phase doesn't trigger onActive). The event that triggered the return to activity is passed as a parameter. It defaults to an empty function.
• startManually: boolean; requires the event-listeners to be bound manually by using the start method, instead of on mount. It defaults to false.
• events: EventTypeName[]; a list of the DOM events that will be listened to in order to monitor the user's activity. The events must be of EventTypeName type (it can be imported). The list defaults to ['mousemove', 'keydown', 'wheel', 'resize', 'mousewheel', 'mousedown', 'pointerdown', 'touchstart', 'touchmove', 'visibilitychange']
• element: HTMLElement; DOM element to which the event listeners will be attached. It defaults to document.

Demo

Here is a working example: https://stackblitz.com/edit/vitejs-vite-dwxlhp?file=src/App.tsx

Acknowledgments

This primitive is inspired by react-idle-timer

Changelog

See CHANGELOG.md