@solid-primitives/refs


Collection of primitives, components and directives that help managing references to JSX elements, keeping track of mounted/unmounted elements.

##### Primitives:

- mergeRefs - Utility for chaining multiple ref assignments with props.ref forwarding.
- resolveElements - Utility for resolving recursively nested JSX children to a single element or an array of elements.
- resolveFirst - Utility for resolving recursively nested JSX children in search of the first element that matches a predicate.
- - Get up-to-date references of the multiple children elements.
- - Get up-to-date reference to a single child element.

Installation

``bash
npm install @solid-primitives/refs


or

mergeRefs

Utility for chaining multiple ref assignments with props.ref forwarding.

$3

`tsx
import { mergeRefs, Ref } from "@solid-primitives/refs";

interface ButtonProps {
ref?: Ref;
}

function Button(props: ButtonProps) {
let ref: HTMLButtonElement | undefined;
onMount(() => {
// use the local ref
});

return (ref = el))} />;
}

// in consumer's component:
let ref: HTMLButtonElement | undefined;

;
`

resolveElements

Utility for resolving recursively nested JSX children to a single element or an array of elements using a predicate.

$3

resolveElements's API is similar to Solid's children helper. It accepts a function that returns JSX children and a predicate function that filters the elements.

`tsx
function Button(props: ParentProps) {
const children = resolveElements(() => props.children);
// ^?: Accessor

return (
// Similarly to children helper, a toArray method is available

{child => (



{child.localName}: {child}



)}

);
}
`

$3

The default predicate is el => el instanceof Element. You can provide a custom predicate to resolveElements to filter the elements.

`tsx
const els = resolveElements(
() => props.children,
(el): el is HTMLDivElement => el instanceof HTMLDivElement,
);

els(); // => HTMLDivElement | HTMLDivElement[] | null
`

On the server side the custom predicate will be ignored, but can be overridden by passing it as a third argument.

The default predicate can be imported from @solid-primitives/refs:

`tsx
import { defaultElementPredicate } from "@solid-primitives/refs";
`

On the client it uses instanceof Element check, on the server it checks for the object with t property. (generated by compiling JSX)

resolveFirst

Utility for resolving recursively nested JSX children in search of the first element that matches a predicate.

$3

resolveFirst matches the API of resolveElements but returns only the first element that matches the predicate.

`tsx
function Button(props: ParentProps) {
const child = resolveFirst(() => props.children);
// ^?: Accessor

return (



{child()?.localName}: {child()}



);
}
`

resolveFirst also accepts a custom predicate as a second argument. See Using a custom predicate section for more details.

Get up-to-date reference to a single child element.

$3

accepts only a ref property for getting the current element or undefined, and requires children to be passed in.

`tsx
import { Ref } from "@solid-primitives/refs";

const [ref, setRef] = createSignal();

{props.children};
`

Get up-to-date references of the multiple children elements.

$3

accepts only a ref property for getting the current array of elements, and requires children to be passed in.

`tsx
import { Refs } from "@solid-primitives/refs";

const [refs, setRefs] = createSignal([]);


{item =>

{item}

}

Hello

;
`

#### Demo

https://stackblitz.com/edit/solid-vite-unocss-bkbgap?file=index.tsx

(run npm start in the terminal)

Types

$3

Type for the ref prop

`ts
export type Ref = T | ((el: T) => void) | undefined;
`

$3

Component properties with types for ref prop

`ts
interface RefProps {
ref?: Ref;
}
``

Changelog

See CHANGELOG.md