@aria-ui/core

@aria-ui/core

A compact and efficient toolkit for building reactive web components. It powers the Aria UI library, but it can also be used independently.

Key Features

Reactive Signals

Uses signals to manage state reactively and automatically update the DOM in response to state changes. It's powered by the mature and battle-tested @preact/signals-core library.

Context Management

Shares signals easily across widely nested HTML elements through context.

DOM Manipulation Utilities

A comprehensive collection of utilities for DOM interactions, enabling declarative management of attributes, styles, and event listeners.

API Reference

BaseElement #

Base class for all custom elements in Aria UI. It implements the ConnectableElement interface.

Group

Elements

constructor

new BaseElement(): BaseElement

ConnectableElement #

Any HTML element that has implemented the addConnectedCallback method.

Group

Elements

addConnectedCallback: (callback: () => void | VoidFunction) => void

Registers a callback to be called when the element is connected to the DOM. This callback can return a cleanup function that will be called when the element is disconnected from the DOM.

Context #

A context is a way to provide and consume signals in a HTML tree.

Group

Contexts

consume

Receives the signal from a parent element.

Returns

A signal that is double-bound to the provided signal.

const consume: (element: ConnectableElement) => Signal<T>;

provide

Provides a signal to all children of the element.

const provide: (
  element: ConnectableElement,
  signal: Signal<T> | ReadonlySignal<T>,
) => void;

CustomElementOptions #

events: EventDeclarations<Events>

props: PropDeclarations<Props>

setup: (element: BaseElement, options: SetupOptions<Props, Events>) => void

ReadonlySignal #

A read-only signal that holds a reactive value.

get value(): T

Deprecated

get

Get the signal's current value.

const get: () => T;

peek

Get the signal's current value without subscribing.

const peek: () => T;

SetupOptions #

emit: EventEmitter<Events, keyof Events>

state: SignalState<Props>

Signal #

A mutable signal that can be used to manage reactive state changes.

set value(value: T)

Deprecated

get

Get the signal's current value.

const get: () => T;

peek

Get the signal's current value without subscribing.

const peek: () => T;

set

Set the value of the signal.

const set: (value: T) => void;

TypedEventTarget #

An interface thats can be used to register event listeners.

addEventListener: (type: EventType, listener: (event: DocumentEventMap[EventType]) => void) => void

removeEventListener: (type: EventType, listener: (event: DocumentEventMap[EventType]) => void) => void

BaseElementConstructor #

Type: new () => BaseElement & Props

EventDeclaration #

Defines options for an event.

Type: { bubbles?: boolean; cancelable?: boolean; composed?: boolean }

EventDeclarations #

Map of event types to EventDeclaration options.

Type: {[EventType in keyof Required<Events>]: EventDeclaration}

EventEmitter #

Type: (type: EventType extends string ? EventType : never, detail: EventType extends string ? Events[EventType]["detail"] : never) => void

PropDeclaration #

Defines options for a property.

Type: { attribute?: boolean | string; default: T; fromAttribute?: (value: string | null) => T; toAttribute?: (value: T) => string | null }

PropDeclarations #

Map of props to PropDeclaration options.

Type: {[K in keyof Required<T>]: PropDeclaration<T[K]>}

SignalState #

A plain object containing signals.

Group

Props and States

Type: {[K in keyof Required<T>]: Signal<T[K]>}

SignalValue #

Extracts the value type from a signal type.

Group

Signals

Type: S extends Signal<infer T> ? T : never

assignProps #

function assignProps<T extends object>(
  defaultProps: Readonly<T>,
  props?: Partial<T>,
): Readonly<T>;

Merges two objects, with the second object taking precedence. Only keys present in the first object will be included in the result.

Group

Props and States

batch #

Groups multiple signal updates into a single batch, optimizing performance by reducing the number of updates.

This is a re-export of batch from @preact/signals-core.

Group

Signals

function batch<T>(fn: () => T): T;

Combine multiple value updates into one "commit" at the end of the provided callback.

Batches can be nested and changes are only flushed once the outermost batch callback completes.

Accessing a signal that has been modified within a batch will reflect its updated value.

Returns

The value returned by the callback.

createComputed #

function createComputed<T>(fn: () => T): ReadonlySignal<T>;

Creates a computed signal that automatically updates its value based on the reactive dependencies it uses. Computed signals are read-only and are used to derive state from other signals, recalculating their value when dependencies change.

Group

Signals

createContext #

function createContext<T>(key: string | symbol, defaultValue: T): Context<T>;

Creates a new context.

Group

Contexts

createSignal #

function createSignal<T>(value: T): Signal<T>;

Creates and returns a new signal with the given initial value. Signals are reactive data sources that can be read and written to, allowing components to reactively update when their values change.

Group

Signals

defineCustomElement #

function defineCustomElement<
  Props extends { [PropName in string | number | symbol]: unknown },
  Events extends { [EventType in string | number | symbol]: CustomEvent },
>(options: CustomElementOptions<Props, Events>): BaseElementConstructor<Props>;

Defines a custom element constructor.

defineEmit #

function defineEmit<
  Events extends { [EventType in string | number | symbol]: CustomEvent },
>(
  element: HTMLElement,
  events: EventDeclarations<Events>,
): (type: keyof Events, detail: Events[keyof Events]["detail"]) => void;

getStateFromProps #

function getStateFromProps<Props extends object>(
  props: PropDeclarations<Props>,
): SignalState<Props>;

mapSignals #

function mapSignals<T extends object>(values: T): SignalState<T>;

Maps every value in the given object to a signal.

Group

Props and States

Deprecated

mapValues #

function mapValues<T extends object>(signals: SignalState<T>): T;

Maps every signal in the given object to its current value.

Group

Props and States

Deprecated

registerCustomElement #

function registerCustomElement(
  name: string,
  element: CustomElementConstructor,
): void;

Adds the given custom element to the custom element registry.

untracked #

Executes a given computation without automatically tracking its dependencies, useful for avoiding unnecessary re-computations.

This is a re-export of untracked from @preact/signals-core.

Group

Signals

function untracked<T>(fn: () => T): T;

Run a callback function that can access signal values without subscribing to the signal updates.

Returns

The value returned by the callback.

useAnimationFrame #

function useAnimationFrame(
  element: ConnectableElement,
  effect: () => void | (() => void | VoidFunction),
): () => void;

Executes an effect in the next animation frame.

The given effect function will be called when the element is connected, and when the dependencies change afterward.

effect could return a function callback. callback will be called in the next animation frame.

callback could return a function dispose. dispose will be called when the effect is disposed.

Group

DOM

useAriaAttribute #

function useAriaAttribute<
  K extends
    | "aria-dropeffect"
    | "aria-grabbed"
    | "aria-atomic"
    | "aria-busy"
    | "aria-controls"
    | "aria-current"
    | "aria-describedby"
    | "aria-details"
    | "aria-disabled"
    | "aria-errormessage"
    | "aria-flowto"
    | "aria-haspopup"
    | "aria-hidden"
    | "aria-invalid"
    | "aria-keyshortcuts"
    | "aria-label"
    | "aria-labelledby"
    | "aria-live"
    | "aria-owns"
    | "aria-relevant"
    | "aria-roledescription"
    | "aria-activedescendant"
    | "aria-colcount"
    | "aria-colindex"
    | "aria-colspan"
    | "aria-description"
    | "aria-posinset"
    | "aria-rowcount"
    | "aria-rowindex"
    | "aria-rowspan"
    | "aria-setsize"
    | "aria-autocomplete"
    | "aria-checked"
    | "aria-expanded"
    | "aria-level"
    | "aria-modal"
    | "aria-multiline"
    | "aria-multiselectable"
    | "aria-orientation"
    | "aria-placeholder"
    | "aria-pressed"
    | "aria-readonly"
    | "aria-required"
    | "aria-selected"
    | "aria-sort"
    | "aria-valuemax"
    | "aria-valuemin"
    | "aria-valuenow"
    | "aria-valuetext",
>(
  element: ConnectableElement,
  key: K,
  compute: () => AriaAttributes[K],
): VoidFunction;

Sets the computed attribute of the element when it's connected.

This is a TypeScript type-safe version of useAttribute.

Group

DOM

useAriaRole #

function useAriaRole(
  element: ConnectableElement,
  role: AriaRole | (() => AriaRole | undefined),
): VoidFunction;

Sets the role attribute of the element when it's connected.

You can pass a string or a compute function that returns a string.

Group

DOM

useAttribute #

function useAttribute(
  element: ConnectableElement,
  key: string,
  compute: () => undefined | null | string | number,
): VoidFunction;

Sets the computed attribute of the element when it's connected.

Group

DOM

useEffect #

function useEffect(
  element: ConnectableElement,
  callback: () => void | VoidFunction,
): () => void;

Registers a callback to be called when the given element is connected to the DOM. It will track which signals are accessed and re-run their callback when those signals change. The callback can return a cleanup function that will be called when the effect is destroyed.

The effect will be destroyed and all signals it was subscribed to will be unsubscribed from, when the element is disconnected from the DOM. You can also manually destroy the effect by calling the returned function.

Group

Signals

useEventListener #

function useEventListener<K extends keyof HTMLElementEventMap>(
  element: ConnectableElement,
  type: K,
  listener: (event: HTMLElementEventMap[K]) => void,
  options?: boolean | AddEventListenerOptions,
): VoidFunction;

Registers an event listener on the element.

Group

DOM

useQuerySelector #

function useQuerySelector<E extends Element>(
  element: ConnectableElement,
  selector: string,
  options?: MutationObserverInit,
): ReadonlySignal<E | null>;

Returns the first element matching the given selector.

Group

DOM

useQuerySelectorAll #

function useQuerySelectorAll<E extends Element>(
  element: ConnectableElement,
  selector: string,
  options?: MutationObserverInit,
): ReadonlySignal<NodeListOf<E>>;

Returns all elements matching the given selector.

Group

DOM

useStyle #

function useStyle<K extends keyof CSSStyleDeclaration>(
  element: ConnectableElement,
  key: K,
  compute: () => CSSStyleDeclaration[K],
): VoidFunction;

Sets the computed style of the element when it's connected.

Group

DOM