IdleLock

Code

import { IdleLock, LockScreen } from "@fadymondy/nasaq/web";export function Shell({ children, user }: { children: React.ReactNode; user: { name: string } }) {  return (    <IdleLock      timeoutSeconds={600}      warningSeconds={30}      lockScreen={({ unlock }) => <LockScreen user={user} methods={["password"]} onUnlock={async (attempt) => (await verify(attempt)) ? unlock() : { error: "Wrong password." }} />}    >      {children}    </IdleLock>  );}declare function verify(attempt: unknown): Promise<boolean>;

Auth · beta

Live examples and controls: IdleLock in the lab.

InstallCopy Anchor Link

npx shadcn@latest add https://docs.nasaqui.com/r/idle-lock.json

Wraps the app so it locks itself after inactivity. Ten seconds of warning is not enough for a person who stepped away, so the "Still there?" dialog counts down first and only its buttons answer it. Then your LockScreen covers the app, which stays mounted but inert and hidden from assistive tech. The timer is a courtesy: expire the session on the server too.

When to useCopy Anchor Link

• An app with sensitive data on shared or unattended screens.
• A "Lock" menu item (controlled locked).

When not to useCopy Anchor Link

• A session that already ended: use session-expired.
• Pages that must not lock, such as a live call: set disabled.

ImportCopy Anchor Link

import { IdleLock, LockScreen } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick startCopy Anchor Link

import { IdleLock, LockScreen } from "@fadymondy/nasaq/web";

export function Shell({ children, user }: { children: React.ReactNode; user: { name: string } }) {
  return (
    <IdleLock
      timeoutSeconds={600}
      warningSeconds={30}
      lockScreen={({ unlock }) => <LockScreen user={user} methods={["password"]} onUnlock={async (attempt) => (await verify(attempt)) ? unlock() : { error: "Wrong password." }} />}
    >
      {children}
    </IdleLock>
  );
}

declare function verify(attempt: unknown): Promise<boolean>;

AnatomyCopy Anchor Link

IdleLock                     data-slot="idle-lock"
├─ app                       data-slot="idle-lock-app"  (inert while locked)
├─ IdleWarningDialog         data-slot="idle-warning"   role="timer"
└─ lock overlay              data-slot="idle-lock-screen"

APICopy Anchor Link

IdleLock: div props plus children, lockScreen (a node, or ({ unlock }) => node), timeoutSeconds (300), warningSeconds (30, 0 for none), locked / defaultLocked / onLockedChange(locked, reason), disabled, unmountWhenLocked, labels.

useIdleLock: { timeoutSeconds, warningSeconds, disabled, onIdle } returns { phase, secondsLeft, stayActive, reset }. Build your own UI on it. It re-checks when the tab becomes visible, so a sleeping laptop locks on wake.

IdleWarningDialog: open, secondsLeft, warningSeconds, onStay, onLockNow, labels.

ExamplesCopy Anchor Link

A manual lock button

import { Button, IdleLock } from "@fadymondy/nasaq/web";
import { useState } from "react";

export function App() {
  const [locked, setLocked] = useState(false);
  return (
    <IdleLock locked={locked} onLockedChange={setLocked} lockScreen={<p>Locked</p>}>
      <Button onClick={() => setLocked(true)}>Lock</Button>
    </IdleLock>
  );
}

AccessibilityCopy Anchor Link

• The countdown is a role="timer", announced every ten seconds and in the last five, not every tick.
• The warning is an alert dialog with focus on "Stay signed in". Input during the warning does not cancel it.
• The locked app is inert and aria-hidden, so focus and screen readers cannot reach it.

RTL & i18nCopy Anchor Link

• English and Arabic built in; pass labels. The countdown is always left to right with Latin digits.

Styling & tokensCopy Anchor Link

• Tokens only. The overlay is z-[60], above dialogs.

Do / Don'tCopy Anchor Link

• Do end the session on the server as well.
• Do use unmountWhenLocked when the page content is confidential.
• Don't set a warning longer than the timeout (it is clamped).

RelatedCopy Anchor Link

• lock-screen
• session-expired

LabCopy Anchor Link

https://docs.nasaqui.com/?path=/docs/components-auth-pages-idle-lock--docs