@aria-ui/utils

Reusable hooks and helpers for building accessible Web Components on top of @aria-ui/core.

This package provides the building blocks that @aria-ui/elements uses internally — ARIA attribute reflection, collection navigation, pointer/keyboard interaction, presence and transition tracking, and more. You can use it to author your own custom elements that follow the same patterns.

Installation

npm install @aria-ui/core @aria-ui/utils
# or
pnpm add @aria-ui/core @aria-ui/utils

API overview

ARIA reflection hooks

Each hook subscribes to a getter and writes the result to the corresponding ARIA attribute on the host element. They are tiny effects, but using them keeps your setup functions declarative and consistent.

| Hook | Reflects to | | ------------------------------------ | ----------------------- | | useAriaDisabled(host, get) | aria-disabled | | useAriaExpanded(host, get) | aria-expanded | | useAriaSelected(host, get) | aria-selected | | useAriaControls(host, get) | aria-controls | | useAriaDescribedBy(host, get) | aria-describedby | | useAriaMultiselectable(host, get) | aria-multiselectable | | useAriaOrientation(host, get) | aria-orientation | | useAriaActivedescendant(host, get) | aria-activedescendant | | useAriaHasPopup(host, get) | aria-haspopup |

Plus low-level helpers getAriaHasPopup(element) and setAriaHasPopup(element, value).

import { useAriaDisabled, useAriaExpanded } from '@aria-ui/utils'

function setupTrigger(host, props) {
  useAriaDisabled(host, () => props.disabled.get())
  useAriaExpanded(host, () => props.open.get())
}

Collections

Collection helpers let you build composite widgets — listboxes, menus, comboboxes — where a parent element coordinates a set of item elements.

| Export | Description | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Collection | An ordered set of items keyed by value, sorted by DOM position. | | getCollectionItemValue(element) | Read the value of a collection item. | | createCollectionStore() | Create a store with getCollection(), getHighlightedValue(), setHighlightedValue(), first(), etc. Designed to be embedded inside your component's own store. | | setupCollectionItem(host, props, getStore, getVisible?) | Register an item element with its parent collection store. Handles registration, ID assignment, and the data-active attribute. | | handleCollectionNavigation(event, collection, getHighlighted, setHighlighted, orientation, loop?) | Process a keydown event for ArrowUp/Down/Left/Right/Home/End and update the highlighted value. Returns true if the event was handled. |

Pointer and keyboard interaction

| Hook | Description | | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | | useEventListener(host, type, listener, options?) | Add a DOM event listener that is automatically removed when the host disconnects. | | useGlobalEventListener(host, type, listener) | Add a window event listener tied to the host's connected lifecycle, deduplicated across hosts. | | usePress(host, onPress) | Unified press handler that fires for mouse, touch, and keyboard (Enter/Space) activation. | | useHover(host, { openDelay, closeDelay, onOpen, onClose }) | Hover tracking with configurable open/close delays. Used by popovers and tooltips. | | usePresence(host, present) | Track whether the host should be present in the DOM, with hooks for unmount-after-animation behavior. | | useTransitionStatus(host, present) | Track CSS transition status ('entering', 'entered', 'exiting', 'exited') for animating overlays. | | useDisabledMountTransitionStyle(host) | Disable CSS transitions during the initial mount, to avoid a flash on first paint. | | createDelayedToggle({ openDelay, closeDelay }) | Standalone delayed open/close state machine. |

Identity and attributes

| Hook | Description | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | useElementId(host) | Assign a stable, unique id to the host element if it doesn't already have one. Returns the id. Useful for aria-activedescendant and aria-controls. | | useAttribute(host, name, get) | Reflect a value to an arbitrary HTML attribute. | | useDataState(host, get) | Reflect a state string to data-state. |

Feature detection

| Export | Description | | --------------------------- | ----------------------------------- | | FeatureDetection | Public feature detection helpers. | | FeatureDetectionInternals | Internal feature detection helpers. |

Re-exports

For convenience, this package also re-exports getNearestOverflowAncestor from @zag-js/dom-query.

Example: a minimal listbox item

import {
  defineCustomElement,
  defineProps,
  onMount,
  type HostElement,
  type State,
} from '@aria-ui/core'
import { setupCollectionItem, useAriaSelected, useEventListener } from '@aria-ui/utils'

import { MyListboxContext } from './my-listbox-context'

interface ItemProps {
  value: string
}

const itemProps = defineProps<ItemProps>({
  value: { default: '', attribute: 'value', type: 'string' },
})

function setupItem(host: HostElement, props: State<ItemProps>) {
  onMount(host, () => {
    host.role = 'option'
  })

  const getStore = MyListboxContext.consume(host)

  setupCollectionItem(host, props, getStore)

  useAriaSelected(host, () => {
    return getStore()?.selectedValues.get().includes(props.value.get()) ?? false
  })

  useEventListener(host, 'click', () => {
    getStore()?.toggle(props.value.get())
  })
}

export class MyItemElement extends defineCustomElement(setupItem, itemProps) {}

License

MIT