Auto Focus
kuiAutoFocus moves focus to its host, or to the first focusable element inside it, after the browser has rendered.
Use it where the next step is obvious, such as the first field of a dialog or a code field that has just appeared. The directive has no styles.
import { KuiAutoFocus } from '@kikita-labs/ui';- The attribute without a value means
true. Focus moves once after the first render when the value istrue, and again every time it changes fromfalsetotrue; a value that staystruenever pulls focus back. - On a wrapper element the directive focuses the first focusable descendant.
kui-otp-inputexposes the same behaviour as its ownautoFocusinput and focuses its first cell.
The directive is conservative about when it moves focus.
- Browser only. Nothing runs during server rendering and the directive never writes the native
autofocusattribute, so the server-rendered page does not move focus before hydration. - No tabindex. A target that cannot take focus is skipped. A disabled, hidden or
inerthost receives no focus, and neither does a host inside aninertsubtree. - Do not steal. On first render the request yields when the user has already focused something outside the dialog or popover of the target. A later
falsetotruechange is an explicit request and always focuses. - Dialogs and popovers. While the dialog or popover that holds the target is animating in, focus waits for the animation for at most one second, so the page does not scroll or jump. While enabled, the host also carries
cdkFocusInitial, so the focus trap ofkuiDialogandkuiDrawerlands on the same element. - Cancel on destroy. A request that has not run yet is dropped when the host is destroyed. Use one
kuiAutoFocuselement per dialog.
There are no outputs, providers or CSS custom properties.
| Name | Type | Default | Description |
|---|---|---|---|
| kuiAutoFocus | boolean | — | Enables focus (default false). The attribute without a value is true, and false to true focuses again. |
| kuiAutoFocusPreventScroll | boolean | — | Focuses without scrolling the element into view (default false). |
Automatic focus can disorient screen-reader users, so keep it off by default.
- A screen-reader user hears only the label of the focused control and misses the content before it. On touch devices it can open the on-screen keyboard and scroll the page. Use it only where focus on arrival is the expected behaviour, and never on the load of a content page.
- Moving focus into a modal dialog is already handled by its focus trap;
kuiAutoFocusonly chooses which element inside it. Use it instead of the nativeautofocusattribute, which runs once per document, cannot repeat and fires before hydration in a server-rendered page. - iOS Safari may not open the on-screen keyboard for focus that does not come from a user gesture, and the directive does not work around that.