Sensors

useFocusWithin

Reactive utility that tracks whether focus is within a container element or any of its descendants. Works like the CSS :focus-within pseudo-class but as a reactive Observable<boolean>.

Demo

Focus Within Container

No Focus

Click on any input inside the container. The status shows whether any child has focus.

import { 
const useRef$: {
    <T = any>(initialValue: null): Ref$<T | null>;
    <T = any>(initialValue: T): Ref$<T>;
    <T = any>(): Ref$<T | null>;
}
useRef$ } from "@usels/core";
import { 
const useFocusWithin: (target: MaybeEventTarget) => UseFocusWithinReturn
useFocusWithin } from "@usels/web";

function 
function MyForm(): JSX.Element
MyForm() {
  const 
const form$: Ref$<HTMLFormElement | null>
form$ = 
useRef$<HTMLFormElement>(): Ref$<HTMLFormElement | null> (+2 overloads)
Core (framework-agnostic) version of useRef$.
Creates an observable element ref with opaque wrapping.

non-null value → Ref$<T>: current, get(), peek() return T
null / no arg → Ref$<T | null>: current, get(), peek() return T | null

Nullability is expressed via the type parameter, mirroring T | null at the call site.
useRef$<
interface HTMLFormElement
HTMLFormElement>();
  const { 
const focused$: any
Whether focus is within the container or any descendants (read-only)
focused$ } = 
function useFocusWithin(target: MaybeEventTarget): UseFocusWithinReturn
Framework-agnostic tracker for whether focus is within a target element or
any of its descendants.
Uses focusin/focusout events with el.matches(':focus-within') to
reliably detect focus state. This approach delegates the check to the
browser's CSS engine, correctly handling edge cases like iframes and
Shadow DOM boundaries where relatedTarget would be null.
useFocusWithin(
const form$: Ref$<HTMLFormElement | null>
form$);

  return (
    <
JSX.IntrinsicElements.form: DetailedHTMLProps<FormHTMLAttributes<HTMLFormElement>, HTMLFormElement>
form 
RefAttributes<HTMLFormElement>.ref?: Ref<HTMLFormElement> | undefined
Allows getting a ref to the component instance.
Once the component unmounts, React will set ref.current to null
(or call the ref with null if you passed a callback ref).
@see ― https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs
ref={
const form$: Ref$<HTMLFormElement | null>
form$}>
      <
JSX.IntrinsicElements.input: DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>
input 
InputHTMLAttributes<HTMLInputElement>.placeholder?: string | undefined
placeholder="Name" />
      <
JSX.IntrinsicElements.input: DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>
input 
InputHTMLAttributes<HTMLInputElement>.placeholder?: string | undefined
placeholder="Email" />
      <
JSX.IntrinsicElements.p: DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>
p>Form has focus: {
const focused$: any
Whether focus is within the container or any descendants (read-only)
focused$.
any
get() ? "Yes" : "No"}</
JSX.IntrinsicElements.p: DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>
p>
    </
JSX.IntrinsicElements.form: DetailedHTMLProps<FormHTMLAttributes<HTMLFormElement>, HTMLFormElement>
form>
  );
}

import { createRef$ } from "@usels/core";
import { createFocusWithin } from "@usels/web";

function MyForm() {
  "use scope"
  const form$ = createRef$<HTMLFormElement>();
  const { focused$ } = createFocusWithin(form$);

  return (
    <form ref={form$}>
      <input placeholder="Name" />
      <input placeholder="Email" />
      <p>Form has focus: {focused$.get() ? "Yes" : "No"}</p>
    </form>
  );
}

Conditional Styling

Use focused$ to conditionally apply styles when any descendant has focus.

// @noErrors
import { useRef$ } from "@usels/core";
import { useFocusWithin } from "@usels/web";

function HighlightedForm() {
  const container$ = useRef$<HTMLDivElement>();
  const { focused$ } = useFocusWithin(container$);

  return (
    <div
      ref={container$}
      style={{
        outline: focused$.get() ? "2px solid blue" : "none",
        padding: "16px",
      }}
    >
      <input placeholder="Focus me" />
      <button>Or me</button>
    </div>
  );
}

Type

Parameters

Parameter	Type	Description
`target`	`MaybeEventTarget`	-

Returns

UseFocusWithinReturn

Name	Type	Description
`focused$`	`ObservableBoolean<boolean>`	Whether focus is within the container or any descendants (read-only)

Source

View on GitHub