@solid-primitives/keyed

@solid-primitives/keyed

Control Flow primitives and components that require specifying explicit keys to identify or rerender elements.

• keyArray - Reactively maps an array by specified key with a callback function - underlying helper for the <Key> control flow.
• Key - Creates a list of elements by mapping items by provided key.
• Entries - Creates a list of elements by mapping object entries.
• MapEntries - Creates a list of elements by mapping Map entries.
• SetValues - Creates a list of elements by mapping Set values.
• Rerun - Causes the children to rerender when the on changes.

Installation

npm install @solid-primitives/keyed
# or
yarn add @solid-primitives/keyed

keyArray

Reactively maps an array by specified key with a callback function - underlying helper for the <Key> control flow.

How to use it

Import

import { keyArray } from "@solid-primitives/keyed";

Basic usage

The keyArray primitive takes 4 arguments:

• list - input list of values to map
• keyFn - key getter, items will be identified by it's value. changing the value is changing the item.
• mapFn - reactive function used to create mapped output item. Similar to Array.prototype.map but both item and index are signals, that could change over time.
• options - a fallback for when the input list is empty or missing (Optional)

const mapped = keyArray(source, (model, index) => {
  const [name, setName] = createSignal(model().name);
  const [description, setDescription] = createSignal(model().description);

  createComputed(() => {
    setName(model().name);
    setDescription(model().description);
  });

  return {
    id: model.id,
    get name() {
      return name();
    },
    get description() {
      return description();
    },
    get index() {
      return index();
    },
    setName,
    setDescription,
  };
});

Notice that both the value and index arguments are signals. Items are identified only by keys, it means that the items could be copied, replaced, changed, but as long as the key is the same, keyArray will treat it as the same item.

<Key>

Creates a list of elements by mapping items by provided key. Similar to Solid's <For> and <Index>, but here, both value and index arguments are signals.

But changing the value does not rerender the element, only where the value is being used.

How to use it

Import

import { Key } from "@solid-primitives/keyed";

Typical usage

Both each and by have to be provided. The fallback prop is optional, it will be displayed when the list in each is missing or empty.

<Key each={items()} by={item => item.id} fallback={<div>No items</div>}>
  {item => <div>{item()}</div>}
</Key>

Key shortcut

prop by can also be an object key

<Key each={items()} by="id">

Index argument

Second argument of the map function is an index signal.

<Key each={items()} by="id">
  {(item, index) => <div data-index={index()}>{item()}</div>}
</Key>

Demo

https://codesandbox.io/s/solid-primitives-keyed-key-demo-gh7gd?file=/index.tsx

<Entries>

Creates a list of elements by mapping object entries. Similar to Solid's <For> and <Index>, but here, render function takes three arguments, and both value and index arguments are signals.

How to use it

import { Entries } from "@solid-primitives/keyed";

<Entries of={object()} fallback={<div>No items</div>}>
  {(key, value) => (
    <div>
      {key}: {value()}
    </div>
  )}
</Entries>;

Index argument

Third argument of the map function is an index signal.

<Entries of={object()} fallback={<div>No items</div>}>
  {(key, value, index) => (
    <div data-index={index()}>
      {key}: {value()}
    </div>
  )}
</Entries>

<MapEntries>

Creates a list of elements by mapping Map entries. Similar to Solid's <For> and <Index>, but here, render function takes three arguments, and both value and index arguments are signals.

How to use it

import { MapEntries } from "@solid-primitives/keyed";

const [map, setMap] = createSignal(new Map());

<MapEntries of={map()} fallback={<div>No items</div>}>
  {(key, value) => (
    <div>
      {key}: {value()}
    </div>
  )}
</MapEntries>;

Index argument

Third argument of the map function is an index signal.

MapEntries is using Map#keys() so the index and resulting JSX will follow the insertion order.

<MapEntries of={map()} fallback={<div>No items</div>}>
  {(key, value, index) => (
    <div data-index={index()}>
      {key}: {value()}
    </div>
  )}
</MapEntries>

<SetValues>

Creates a list of elements by mapping Set values. Similar to Solid's <For> and <Index>, but here, render function takes two arguments, the value and the index argument as a signal.

How to use it

import { SetValues } from "@solid-primitives/keyed";

const [set, setSet] = createSignal(new Set());

<SetValues of={set()} fallback={<div>No items</div>}>
  {value => <div>{value}</div>}
</SetValues>;

Index argument

Second argument of the map function is an index signal.

SetValues is using Set#values() so the index and resulting JSX will follow the insertion order.

<SetValues of={set()} fallback={<div>No items</div>}>
  {(value, index) => <div data-index={index()}>{value}</div>}
</SetValues>

<Rerun>

Causes the children to rerender when the on key changes. Equivalent of v-key in vue, and {#key} in svelte.

Note: Since Solid 1.5.0 the <Show> component has a keyed prop that works very similarly to <Rerun>.

Import

import { Rerun } from "@solid-primitives/keyed";

How to use it

You have to provide a on prop. Changing it, will cause the children to rerender.

const [count, setCount] = createSignal(0);

// will rerender whole <button>, instead of just text
<Rerun on={count()}>
  <button onClick={() => setCount(p => ++p)}>{count()}</button>
</Rerun>;

// or pass a function
<Rerun on={() => count()}/>

// or an array of dependencies
<Rerun on={[count, name, length]}/>

Passing a function as children

You can treat on prop like sources argument of the Solid's on helper, and the children as the second, callback argument.

<Rerun on={[count, className]}>
  {([count, className]) => (
    <button class={className} onClick={() => setCount(p => ++p)}>
      {count}
    </button>
  )}
</Rerun>

Using with Transition

<Rerun> can be used together with solid-transition-group to animate single component's transition, on state change.

<Transition name="your-animation" mode="outin">
  <Rerun on={count()}>
    <button onClick={() => setCount(p => ++p)}>{count()}</button>
  </Rerun>
</Transition>

DEMO

https://codesandbox.io/s/solid-primitives-keyed-rerun-demo-14vjr?file=/index.tsx

Changelog

See CHANGELOG.md