JSX properties

ref

ref provides access to a DOM element after Solid creates it. It accepts an assignable variable, a callback, or a nested array of callbacks.


Type

type RefCallback<T> = (element: T) => void;
type Ref<T> = T | RefCallback<T> | undefined | Ref<T>[];

ref is available on intrinsic DOM elements. It does not require an import.


Assign an element

Pass an assignable variable to store the element:

function SearchField() {
let input!: HTMLInputElement;
return (
<>
<input ref={input} type="search" />
<button type="button" onClick={() => input.select()}>
Select query
</button>
</>
);
}

A callback receives the same element:

<input ref={(element) => (input = element)} />

Compose callbacks

Pass an array when several independent behaviors need the element:

function autofocus(element: HTMLInputElement) {
element.autofocus = true;
}
<input
ref={[(element) => (input = element), autofocus, registerAnalytics("search")]}
/>;

Solid recursively flattens nested ref arrays and invokes each callback in order. This composes element access, reusable directives, and third-party integrations without a wrapper callback.


Ownership and cleanup

A ref callback runs the way a render effect's callback runs when the element is created: untracked, in the context of the pass that creates the element, so its reads see what that pass is building. It owns nothing, and its return value is ignored. Do not create owned reactive primitives or return cleanup functions from a ref callback. In development, creating a memo, effect, or root inside one throws PRIMITIVE_IN_EFFECT_CALLBACK, and onCleanup throws CLEANUP_IN_FORBIDDEN_SCOPE. Writes, refresh, action calls, and onFlush are allowed, as in an effect callback.

When a reusable directive needs setup and cleanup, create those primitives in an owned factory and return only the callback that receives the element. See Refs and directives for the complete pattern, and Integrate non-Solid code for a chart, a map, and a web component driven through refs.

Last updated: 11/16/26, 7:06 AMEdit this pageReport an issue with this page