npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@solid-primitives/refs

v1.0.8

Published

Library of primitives, components and directives for SolidJS that help managing references to JSX elements.

Downloads

122,270

Readme

@solid-primitives/refs

turborepo size version stage

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.
  • <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