@solid-primitives/refs
v1.0.8
Published
Library of primitives, components and directives for SolidJS that help managing references to JSX elements.
Downloads
120,773
Readme
@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 multipleref
assignments withprops.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.<Refs>
- Get up-to-date references of the multiple children elements.<Ref>
- Get up-to-date reference to a single child element.
Installation
npm install @solid-primitives/refs
# or
pnpm add @solid-primitives/refs
# or
yarn add @solid-primitives/refs
mergeRefs
Utility for chaining multiple ref
assignments with props.ref
forwarding.
How to use it
import { mergeRefs, Ref } from "@solid-primitives/refs";
interface ButtonProps {
ref?: Ref<HTMLButtonElement>;
}
function Button(props: ButtonProps) {
let ref: HTMLButtonElement | undefined;
onMount(() => {
// use the local ref
});
return <button ref={mergeRefs(props.ref, el => (ref = el))} />;
}
// in consumer's component:
let ref: HTMLButtonElement | undefined;
<Button ref={ref} />;
resolveElements
Utility for resolving recursively nested JSX children to a single element or an array of elements using a predicate.
How to use it
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.
function Button(props: ParentProps) {
const children = resolveElements(() => props.children);
// ^?: Accessor<Element | Element[] | null>
return (
// Similarly to `children` helper, a `toArray` method is available
<For each={children.toArray()}>
{child => (
<div>
{child.localName}: {child}
</div>
)}
</For>
);
}
Using a custom predicate
The default predicate is el => el instanceof Element
. You can provide a custom predicate to resolveElements
to filter the elements.
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
:
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.
How to use it
resolveFirst
matches the API of resolveElements
but returns only the first element that matches the predicate.
function Button(props: ParentProps) {
const child = resolveFirst(() => props.children);
// ^?: Accessor<Element | null>
return (
<div>
{child()?.localName}: {child()}
</div>
);
}
resolveFirst
also accepts a custom predicate as a second argument. See Using a custom predicate
section for more details.
<Ref>
Get up-to-date reference to a single child element.
How to use it
<Ref>
accepts only a ref
property for getting the current element or undefined
, and requires children
to be passed in.
import { Ref } from "@solid-primitives/refs";
const [ref, setRef] = createSignal<Element | undefined>();
<Ref ref={setRef}>{props.children}</Ref>;
<Refs>
Get up-to-date references of the multiple children elements.
How to use it
<Refs>
accepts only a ref
property for getting the current array of elements, and requires children
to be passed in.
import { Refs } from "@solid-primitives/refs";
const [refs, setRefs] = createSignal<Element[]>([]);
<Refs ref={setRefs}>
<For each={my_list()}>{item => <div>{item}</div>}</For>
<Show when={show()}>
<div>Hello</div>
</Show>
</Refs>;
Demo
https://stackblitz.com/edit/solid-vite-unocss-bkbgap?file=index.tsx
(run npm start
in the terminal)
Types
Ref
Type for the ref
prop
export type Ref<T> = T | ((el: T) => void) | undefined;
RefProps
Component properties with types for ref
prop
interface RefProps<T> {
ref?: Ref<T>;
}
Changelog
See CHANGELOG.md