@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.

Interfaces

CustomElementOptions<Props, Events>

Properties

events: EventDeclarations<Events>

props: PropDeclarations<Props>

setup: (element, options) => void

ReadonlySignal<T>

A read-only signal that holds a reactive value.

Accessors

get value(): T

Deprecated

Methods

get(): T

Get the signal's current value.

peek(): T

Get the signal's current value without subscribing.

SetupOptions<Props, Events>

Properties

emit: EventEmitter<Events>

state: SignalState<Props>

Signal<T>

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

Accessors

set value(value): void

Deprecated

Methods

get(): T

Get the signal's current value.

peek(): T

Get the signal's current value without subscribing.

set(value): void

Set the value of the signal.

TypedEventTarget<EventType>

An interface thats can be used to register event listeners.

Properties

addEventListener: (type, listener) => void

removeEventListener: (type, listener) => void

Type Aliases

BaseElementConstructor()<Props>

type BaseElementConstructor<Props> = () => BaseElement & Props

EventDeclaration

type EventDeclaration = { bubbles?: boolean; cancelable?: boolean; composed?: boolean; }

Defines options for an event.

Properties

bubbles?: boolean

Whether the event bubbles.

Default

false

cancelable?: boolean

Whether the event is cancelable.

Default

true

composed?: boolean

Whether the event is composed.

Default

false

EventDeclarations<Events>

type EventDeclarations<Events> = { [EventType in keyof Required<Events>]: EventDeclaration }

Map of event types to EventDeclaration options.

EventEmitter()<Events, EventType>

type EventEmitter<Events, EventType> = (type, detail) => void

PropDeclaration<T>

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

Defines options for a property.

Properties

attribute?: boolean | string

Indicates how and whether the property becomes an observed attribute. If the value is false, the property is not added to observedAttributes. If true or absent, the kebab-case version of the property name is observed (e.g. fooBar becomes foo-bar). If a string, the string value is observed (e.g attribute: 'custom-foo-bar').

default: T

The default value of the property.

fromAttribute?: (value) => T

Called to convert an attribute value to a property value.

toAttribute?: (value) => string | null

Called to convert a property value to an attribute value.

PropDeclarations<T>

type PropDeclarations<T> = { [K in keyof Required<T>]: PropDeclaration<T[K]> }

Map of props to PropDeclaration options.

Functions

defineCustomElement()

function defineCustomElement<Props, Events>(options): BaseElementConstructor<Props>

Defines a custom element constructor.

defineEmit()

function defineEmit<Events>(element, events): (type, detail) => void

getStateFromProps()

function getStateFromProps<Props>(props): SignalState<Props>

registerCustomElement()

function registerCustomElement(name, element): void

Adds the given custom element to the custom element registry.

Contexts

Context<T>

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

Methods

consume(element): Signal<T>

Receives the signal from a parent element.

provide(element, signal): void

Provides a signal to all children of the element.

createContext()

function createContext<T>(key, defaultValue): Context<T>

Creates a new context.

DOM

useAnimationFrame()

function useAnimationFrame(element, effect): () => 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.

useAriaAttribute()

function useAriaAttribute<K>(element, key, compute): VoidFunction

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

This is a TypeScript type-safe version of useAttribute.

useAriaRole()

function useAriaRole(element, role): 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.

useAttribute()

function useAttribute(element, key, compute): VoidFunction

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

useEventListener()

function useEventListener<K>(element, type, listener, options?): VoidFunction

Registers an event listener on the element.

useQuerySelector()

function useQuerySelector<E>(element, selector, options): ReadonlySignal<null | E>

Returns the first element matching the given selector.

useQuerySelectorAll()

function useQuerySelectorAll<E>(element, selector, options): ReadonlySignal<NodeListOf<E>>

Returns all elements matching the given selector.

useStyle()

function useStyle<K>(element, key, compute): VoidFunction

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

Elements

BaseElement

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

Constructors

Constructor

new BaseElement(): BaseElement

ConnectableElement

Any HTML element that has implemented the addConnectedCallback method.

Properties

addConnectedCallback: (callback) => 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.

Props and States

SignalState<T>

type SignalState<T> = { [K in keyof Required<T>]: Signal<T[K]> }

A plain object containing signals.

assignProps()

function assignProps<T>(defaultProps, props?): Readonly<T>

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

~~mapSignals()~~

function mapSignals<T>(values): SignalState<T>

Maps every value in the given object to a signal.

Deprecated

~~mapValues()~~

function mapValues<T>(signals): T

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

Deprecated

Signals

SignalValue<S>

type SignalValue<S> = S extends Signal<infer T> ? T : never

Extracts the value type from a signal type.

batch()

const batch: <T>(fn) => T = _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.

untracked()

const untracked: <T>(fn) => T = _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.

createComputed()

function createComputed<T>(fn): 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.

createSignal()

function createSignal<T>(value): 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.

useEffect()

function useEffect(element, callback): () => 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.