Reference

This section is the native API reference for Lit^sx.

It covers the APIs you author directly in Lit^sx code:

• primitives such as SuspenseBoundary and SuspenseList
• hooks for state, effects, transitions, refs, and external stores
• static hoists such as ^name(...), documented in the authoring guides rather than exposed as runtime imports
• styling helpers for dynamic host style values
• the authored surface of the framework, not the lower-level runtime helpers behind compilation

If you are learning the framework, read this section the same way you would read the reference docs of any other UI framework: as the place to understand what each API is for, when to use it, and what mental model to apply.

What This Section Is For

Use this reference when you already know the feature you need and want the native Lit^sx API for it.

• state and derived values
• async rendering and recoverable errors
• events and lifecycle hooks
• refs and imperative escape hatches
• host-level dynamic styling

If you are still learning the authoring model itself, start with the guides first and then come back here as the API map.

What Is Not Here

This section is intentionally not the place for:

• Babel transform internals
• React compatibility lowering details
• generated transform contracts
• implementation-level runtime helpers that exist only to support compilation

Those live elsewhere:

• Transform Recipes
• Migrating from React
• Framework Reference

Start Here

• Detailed Reference Pages
• Primitives
• Events
• Refs
• JSX Authoring

Most Used APIs

If you want the shortest path through the native surface, start here:

• useState for local component state
• useAsyncState for authoritative async mutations and pending/error state
• useRef for mutable refs and imperative coordination
• useEvent for stable event handlers tied to component lifecycle
• useEmit for custom DOM events as part of the public component API
• SuspenseBoundary for async subtrees
• ErrorBoundary for recoverable rendering failures
• useStyle for dynamic host style values

Compile-Time Authoring

Some Lit^sx features are authored natively but are not runtime imports.

The most important examples are static hoists such as ^styles(...), ^properties(...), and other ^name(...) forms. They are part of the authoring model, but they belong in the guides because they are compile-time syntax, not ordinary importable APIs.

Start here for that layer:

• JSX Authoring
• Static Hoists
• Property Inference

Primitives

Primitives shape asynchronous UI directly in authored JSX.

• SuspenseBoundary
• SuspenseList
• ErrorBoundary

Start with these if you are learning how Lit^sx models async rendering and recoverable subtree failures.

Hooks

Hooks are the main authored API for state, effects, transitions, and imperative escape hatches.

The rough mental model is:

• state hooks own local and derived state
• lifecycle hooks connect authored code to rendering and DOM timing
• ref hooks own imperative access and public handles
• integration hooks bridge to external stores or environment state

State And Derived Values

• useState
• useReducedState
• useControlledState
• useAsyncState
• useMemoValue
• useOptimistic
• useDeferredValue
• useTransition

Effects And Lifecycle Work

• useOnConnect
• useEvent
• useEmit
• useAfterUpdate
• useOnCommit

Refs And Imperative APIs

• Refs Guide
• useRef
• useCallbackRef
• useExpose
• useHost
• useHostContent
• usePrevious
• useSlot
• useStableCallback
• useTextContent

External State

• useExternalStore

Styling

Styling helpers let authored Lit^sx code drive dynamic host-level style values.

• useStyle

Suggested Reading Paths

If you are new to Lit^sx:

1. Read JSX Authoring.
2. Read useState, useAsyncState, useOptimistic, useOnConnect, useEvent, useEmit, useAfterUpdate, and useOnCommit.
3. Then move to ErrorBoundary, SuspenseBoundary, and SuspenseList.

If you are building more interactive components:

1. Start with useState and useReducedState.
2. Add useMemoValue, useDeferredValue, useTransition, and useOptimistic when derived work or async interactions become more expensive.
3. Use useRef, useHost, useHostContent, useTextContent, useSlot, and useExpose only when the component needs DOM or imperative coordination.