useKeyboardLayoutGuide@astryxdesign/core v0.7.5 · useKeyboardLayoutGuide

Usage

Experimental: this hook and everything exported from @astryxdesign/core/keyboard/experimental are outside the stable compatibility promise and may change or be removed in a patch release. The web’s UIKeyboardLayoutGuide: where the software keyboard covers the page and how it moves, for content that stays above it (a composer, a field docked at the bottom). Mobile Safari reports the keyboard once, after it starts to move, and a hide only after it ends; each transition is dated back to the keyboard’s own start, and a hide starts at the blur. Chrome reports the keyboard at the start of its slide and plays Android’s keyboard curve from there. Move your element from the listener with rideKeyboard(animator, values, transition), which uses UIKit’s keyboard spring on iOS and Android’s curve on Chrome from transition.start, so it rides in step with the keyboard. The same subpath exports getKeyboardLayoutGuide(window) for non-React code.

ts
import {useKeyboardLayoutGuide} from '@astryxdesign/core'

Best practices

GuidancePractices
Do

Animate with rideKeyboard: it starts at transition.start on the keyboard’s own motion and keeps it under Reduce Motion, as the keyboard does.

Do

Pass overlayFor for a field that moves itself above the keyboard, so Chrome does not also pan the page to reveal it.

Do

Lift a docked element only while a keyboard is up: to > 0 ? max(0, restingBottom - (innerHeight - to)) : 0.

Don't

Read the visual viewport every frame to follow the keyboard: Safari reports one final value, so there is nothing to follow.

Don't

Rely on this API from stable product code: it is experimental and may change in a patch release.

Parameters

ParamTypeDescription
onTransition
(transition:
) => void

Called with every keyboard transition while the component is mounted: {kind, from, to, start, velocity, animated, predicted, curve}, insets in CSS px from the bottom of the layout viewport, start on the document timeline, curve the eased slide on Chrome (null for UIKit’s spring). Read through a ref, so a new function on each render subscribes nothing new.

options.overlayFor
RefObject<Element | null>

A field that keeps itself above the keyboard. While focus is in it, the page overlays the keyboard on Chrome (navigator.virtualKeyboard.overlaysContent), so Chrome neither resizes nor pans the page to reveal the field. The flag is set only if the page had not set it, and restored when focus leaves the field or the component unmounts.

Returns

FieldTypeDescription
guide
| null

The window’s guide (null while rendering on a server): inset (where the keyboard rests), transition (the latest one), presentation(time) (the inset on screen at any time), subscribe(listener), profile (webkit on iOS, chromium elsewhere) and overlayWhileFocused(element).

Use with shadcn

Already using the shadcn registry workflow? Install the real Astryx package and a local public re-export. Component implementation source stays in Astryx.

This install URL expires with the draft preview.
bash
npx shadcn@4.19.0 add https://astryx-20jglg0rs-fbopensource.vercel.app/shadcn/hooks/use-keyboard-layout-guide.json