@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

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;
}

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

  return <button> (ref = el))} /&gt;;
}

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

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>

  return (
    // Similarly to `children` helper, a `toArray` method is available
    
      {child =&gt; (
        <div>
          {child.localName}: {child}
        </div>
      )}
    
  );
}

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>

  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.

``

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

How to use it

`` 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>();

{props.children};

``

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

How to use it

`` 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([]);


  {item =&gt; <div>{item}</div>}
  
    <div>Hello</div>
  
;

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 | ((el: T) => void) | undefined;

RefProps

Component properties with types for ref prop

interface RefProps {
  ref?: Ref;
}

Changelog

See CHANGELOG.md