→ Session
Session Provider
Shares one useKnockCodes session across a tree, so multiple components stay in sync.
Best used for Any screen where more than one component (a gate, a logout button, a timeout banner) needs the same session.
useKnockCodesContext() throws outside a provider — there's no meaningful standalone default for "give me
the shared session" when nothing established one.
- components
- knock-codes
- core
- react
"use client";
import { createContext, useContext, type ReactNode } from "react";
import { useKnockCodes } from "./useKnockCodes.ts";
import type { KnockCodesConfig, UseKnockCodesResult } from "./types.ts";
const KnockCodesContext = createContext<UseKnockCodesResult | null>(null);
export interface KnockCodesProviderProps extends KnockCodesConfig {
children: ReactNode;
}
/**
* Shares one `useKnockCodes` session across a whole tree, so multiple
* components — a gate, a `LogoutButton`, a `SessionTimeoutBanner` — read and
* act on the same unlock state instead of each running an independent
* verification/session lifecycle. Optional: `useKnockCodes` or `<KnockCodes>`
* work standalone with no provider; reach for this only when two or more
* components need to share one session.
*/
export function KnockCodesProvider({ children, ...config }: KnockCodesProviderProps) {
const state = useKnockCodes(config);
return <KnockCodesContext.Provider value={state}>{children}</KnockCodesContext.Provider>;
}
/** Throws outside an `<KnockCodesProvider>` — there is no meaningful standalone default. */
export function useKnockCodesContext(): UseKnockCodesResult {
const context = useContext(KnockCodesContext);
if (!context) {
throw new Error("Knock Codes: useKnockCodesContext must be used within an <KnockCodesProvider>.");
}
return context;
}
Add this block to your project
CLI
npx shadcn@latest add http://localhost:3000/r/react/session-provider.jsonRunning this site somewhere other than localhost? Set NEXT_PUBLIC_SITE_URL and this command switches to that host automatically.
Also installs
- Knock Codes Core
- Knock Codes Types
- useKnockCodes
Files created (7)
- 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/KnockCodesProvider.tsx
No CLI? Copy the files by hand
- Open the Code tab in the preview above.
- Create each path listed below in your project and paste its contents in.
- Do the same for anything listed under “Also installs”, if present.
→ Props
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
| expectedHash | string | — | SHA-256 hex hash to verify against, for local mode. |
| verify | VerifyFn | — | Custom async verification function, for server mode. |
| storage | "localStorage" | "sessionStorage" | "memory" | "localStorage" | Where the unlocked session persists. |
| timeout | number | 1800000 | Session lifetime in milliseconds. |
| children * | ReactNode | — | Everything that should read the shared session via useKnockCodesContext(). |
Accessibility
Renders no UI of its own — purely a context boundary. Accessibility is entirely a function of whatever you render inside it.
Customization
Reach for this only when two or more components need to share one session — a gate, a Logout Button, and a Session Timeout Banner all reading and acting on the same unlock state. `useKnockCodes`/`<KnockCodes>` remain the right choice standalone.
→ 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.
- Logout ButtonReads the shared session from a Session Provider and clears it on click.
- Session Timeout BannerWarns before the shared session expires, with a one-click way to log out immediately.
- Access ReceiptA small session audit strip shown after unlock — timestamp, storage mode, timeout, and verification strategy.
- Knock CodesThe main gate — renders children when unlocked, otherwise an access-code prompt.