Skip to content

Installation

Install @diffgazer/keys as a package, or copy standalone hooks into your app with dgadd.

@diffgazer/keys ships two ways. Install the package when you need the provider-backed hooks; copy standalone hooks with dgadd when you want to own the source outright. The introduction covers which hooks fall into each group.

Info:

Installing via dgadd: Only standalone hooks (keys/navigation, keys/focus-trap, keys/focus-restore, keys/scroll-lock) are copyable; provider-backed hooks are package-only. For the full command and flag reference — init, add, list, diff, remove — see the dgadd CLI reference.

Info:

Before publication: Diffgazer packages are not yet published to npm, so npm install @diffgazer/keys and pnpm exec dgadd do not resolve yet. Pack the workspace packages from a checkout and install those tarballs in the target app — see the canonical Consumption Paths section.

Package install

Use the package when you need provider-backed hooks: KeyboardProvider, useKey, useScope, useScopedNavigation, useActionRowNavigation, or useFocusZone.

01.

Install the package

Before publication, pack @diffgazer/keys from a checkout of the repository:

bash
pnpm --filter @diffgazer/keys pack --pack-destination /tmp/diffgazer-packs

Then install that tarball in the target app:

bash
npm install /tmp/diffgazer-packs/diffgazer-keys-*.tgz

After publication, this becomes:

bash
npm install @diffgazer/keys
02.

Wrap your app and use a hook

Provider-backed hooks read from KeyboardProvider, so mount it above any component that uses them:

tsx
import { KeyboardProvider, useKey } from "@diffgazer/keys"

Copy standalone hooks

Use dgadd for source-owned standalone hooks with no package runtime dependency. The copied hooks land in your configured hooks directory, usually src/hooks.

01.

Initialize dgadd

bash
pnpm exec dgadd init
02.

Add the hooks you need

Add one hook, or several at once:

bash
pnpm exec dgadd add keys/navigation
pnpm exec dgadd add keys/focus-trap keys/focus-restore keys/scroll-lock

For a single item you can drop the add keyword — pnpm exec dgadd keys/navigation resolves the same way.

Direct shadcn / manual copy

The hosted registry is not public yet because r.b4r7.dev does not resolve. Use this source checkout or a local registry preview until the endpoint returns 200.

Use pnpm exec dgadd add keys/navigation, or copy the source from the hook source sections in these docs. Place each file at the path shown above its source block, such as src/hooks/use-navigation.ts and src/hooks/utils/navigation-items.ts.

API availability by path

Standalone hooks install through every path. Provider-backed APIs depend on KeyboardProvider and ship only with the package.

APIPackagedgaddDirect copy
useNavigationYesYesYes
useFocusTrapYesYesYes
useFocusRestoreYesYesYes
useScrollLockYesYesYes
KeyboardProviderYesNoNo
useKeyYesNoNo
useScopeYesNoNo
useScopedNavigationYesNoNo
useActionRowNavigationYesNoNo
useFocusZoneYesNoNo
keysYesNoNo
useKeyboardContextYesNoNo
useOptionalKeyboardContextYesNoNo

With @diffgazer/ui

Keyboard-enabled UI components can install their required hooks for you. Pick the integration mode that matches how you consume keys:

bash
pnpm exec dgadd add ui/menu --integration copy
pnpm exec dgadd add ui/dialog --integration keys

copy writes local hook source; keys imports from the @diffgazer/keys package.

Where to go next