Skip to content
← Blocks / Core

Knock Codes

A copy-paste React access screen for gating a whole page or app root — local hash or server verification, one prop swap between them. Zero dependencies.

CoreCore Blockcoregate

Best used for The default choice for gating a whole page or app root in local mode.

The component every other block in this library either wraps or composes on. Local SHA-256 verification by default; swap expectedHash for verify to upgrade to server-mode protection with no other code changes. Inside a <KnockCodesProvider>, this joins the shared session so a <LogoutButton> in the same tab actually relocks the gate. Nothing is rendered until storage has been read (ready), so a returning visitor doesn't flash the PIN UI.

Outer Positioning Variants

  • Full Page (variant="page"): Centers the gate vertically and horizontally across the viewport (min-h-[100dvh]). Replaces the thin StandaloneGate wrapper.
  • Inline Shell (variant="inline"): Flows naturally inside your existing layout (e.g. inside a sidebar, modal, or section card). Replaces the thin EmbeddedGate wrapper.
// Usage

Minimal setup

<KnockCodes expectedHash={process.env.NEXT_PUBLIC_KNOCK_HASH}>
  <YourApp />
</KnockCodes>
FIG.01Demo code: 4242
Installation

Add this block to your project

Recommended

npx shadcn@latest add @knock-codes/knock-codes

Also installs

  • Knock Codes Core
  • Knock Codes Types
  • useKnockCodes
  • cx (classname helper)
  • Gate Wrapper
  • PIN Input

These install together as one atomic unit — even a presentational or read-only piece needs the full verification stack (hook, types, core) behind it to actually run.

Files created (11)

  • components/knock-codes/core/hash.ts
  • components/knock-codes/core/verify.ts
  • components/knock-codes/core/session.ts
  • components/knock-codes/core/storage.ts
  • components/knock-codes/react/types.ts
  • components/knock-codes/react/useKnockCodes.ts
  • components/knock-codes/react/KnockCodesContext.tsx
  • components/knock-codes/react/cx.ts
  • components/knock-codes/react/GateWrapper.tsx
  • components/knock-codes/react/PinInput.tsx
  • components/knock-codes/react/KnockCodes.tsx
Other ways

GitHub shorthand

npx shadcn@latest add trivedi-vatsal/knock-codes/knock-codes

Copy the files by hand

  1. Open the Code tab in the preview above.
  2. Create each path listed below in your project and paste its contents in.
  3. Do the same for anything listed under “Also installs”, if present.
// Props

API reference

PropTypeDefaultDescription
expectedHashstringSHA-256 hex hash to verify against, for local mode. Mutually exclusive with verify.
verifyVerifyFnCustom async verification function, for server mode. Mutually exclusive with expectedHash.
storage"localStorage" | "sessionStorage" | "memory""localStorage"Where the unlocked session persists.
storageKeystring"knock-codes:session"Storage key the session is written under.
timeoutnumber1800000Session lifetime in milliseconds (30 minutes).
activityTrackingbooleanfalseSliding-timeout model — interaction rewrites expiry instead of a fixed TTL.
validateSession(session: KnockCodesSession) => boolean | Promise<boolean>Called when a session is read from storage. Return false or throw to reject it (server-mode token check). Omitted: expiry is the only restore check.
children *ReactNodeRendered once unlocked.
labelsKnockCodesLabelsOverrides for every user-facing string.
variant"page" | "inline""page"Outer positioning — full-page centered, or flows inline in an existing layout.
classNamestringExtra classes on the outer wrapper.

Exactly one of expectedHash or verify is required.

Notes

Accessibility

The access-code field is a labeled, masked text input with native paste support. Errors and the submitting state announce through an aria-live="polite" status region, so screen reader users hear "Checking..." and any error without focus moving. The whole flow works keyboard-only: tab to the field, type, Enter to submit.

Customization

Every string is overridable through the `labels` prop for localization. The wrapper has no fixed visual opinions beyond the default card — pass `className` to restyle the shell, or skip this component and call `useKnockCodes` directly to build a fully custom prompt.

Security & Verification

Need a hash? Use the hash generator on Getting Started — computed locally, never sent anywhere.

The honest version

Knock Codes stops casual visitors, search engines, and forwarded links. Local mode does not stop anyone who opens DevTools — the hash ships in your client bundle by design. Server mode (swap one prop) hides the hash from the client; children you already bundled are still in the JavaScript, and a forged session works unless you wire validateSession. A velvet rope, with an optional real lock. Never marketed as more than that.

// Ready-made

Used in these templates

Want the whole screen instead of assembling it yourself? These templates already build on this block.

// Compose with

Blocks that pair well with this one

These combine naturally with this block, whether as a shared shell, a shared session, or a common fallback.