Range

Control Flow Primitives for number ranges: createNumericRange, mapRange, indexRange, repeat, and their JSX component counterparts.

npm i @solid-primitives/range@next

Control Flow Primitives for displaying a number range or given number of elements.

• createNumericRange - Reactively generates a number array for a given range. Convenient companion to the built-in <For>.
• repeat - Primitive for mapping a number of elements. Underlying helper for the <Repeat> control flow.
• <Repeat> - Control Flow Component for displaying a number of elements. ⚠️ Deprecated — use Solid 2.0's built-in <Repeat>.
• mapRange - Primitive for mapping a number range of given start, end, and step values. Underlying helper for the <Range> control flow.
• <Range> - Control Flow Component for displaying a number range of elements.
• indexRange - Primitive for mapping a number range while keeping previous elements of the same index. Underlying helper for the <IndexRange> control flow.
• <IndexRange> - Control Flow Component for displaying a number range of elements, where elements receive a number value as signal.

createNumericRange

Reactively generates an array of numbers for the given range. Mirrors the range() API from Python — one argument gives [0, to), two or three give [from, to) with an optional step.

All arguments accept either a plain number or a reactive accessor. Pairs naturally with Solid 2.0's built-in <For>.

// static
createNumericRange(5)         // [0, 1, 2, 3, 4]
createNumericRange(2, 7)      // [2, 3, 4, 5, 6]
createNumericRange(0, 10, 2)  // [0, 2, 4, 6, 8]
createNumericRange(5, 0)      // [5, 4, 3, 2, 1]  (descending)

// reactive
const [to, setTo] = createSignal(5);
const nums = createNumericRange(to);  // updates when `to` changes

// compose with <For> — pass the signal, not the called value
const nums = createNumericRange(count);
<For each={nums()}>{n => <div>{n}</div>}</For>

Definition

function createNumericRange(to: MaybeAccessor<number>): Accessor<number[]>;
function createNumericRange(
  start: MaybeAccessor<number>,
  to: MaybeAccessor<number>,
  step?: MaybeAccessor<number>,
): Accessor<number[]>;

repeat

Reactively maps a number range of specified length with a callback function - underlying helper for the <Repeat> control flow.

const [length, setLength] = createSignal(10);
const mapped = repeat(length, index => {
  const [value, setValue] = createSignal(index);
  createEffect(
    () => value(),
    v => {
      /* react to value */
    },
  );
  return value;
});

Definition

function repeat<T>(
  times: Accessor<number>,
  mapFn: (i: number) => T,
  options?: {
    fallback?: Accessor<T>;
  },
): Accessor<T[]>;

<Repeat>

Deprecated — Solid 2.0 ships a built-in <Repeat> in @solidjs/web. Migrate to that:

import { Repeat } from "@solidjs/web";

// basic — children receive a plain index number
<Repeat count={10}>{(i) => <div>{i}</div>}</Repeat>

// with offset (replaces a start > 0 use-case)
<Repeat count={8} from={2}>{(i) => <div>{i}</div>}</Repeat>

// with fallback — wrap in <Show> since built-in <Repeat> has no fallback prop
<Show when={count() > 0} fallback={<p>no items</p>}>
  <Repeat count={count()}>{(i) => <div>{i}</div>}</Repeat>
</Show>

Note: The built-in <Repeat> does not diff — it re-renders all children when count changes. If incremental creation/disposal of children is important for your use case, keep using this primitive.

Control Flow component for displaying a specified number of elements.

The times prop is reactive – changing it will only create new elements for added numbers.

<Repeat times={10}>
   <div></div>
</Repeat>

// with a render prop:
<Repeat times={10}>
   {n => <div>{n}</div>}
</Repeat>

// with fallback:
<Repeat times={0} fallback={<p>no items...</p>}>
   <div></div>
</Repeat>

Definition

function Repeat<T>(props: {
  times: number;
  fallback?: T;
  children: ((index: number) => T) | T;
}): Accessor<T[]>;

mapRange

Reactively maps a number range of specified start, to and step, with a callback function - underlying helper for the <Range> control flow.

All start, to and step arguments are accessors, and changing them will cause the mapped array to be recalculated, mapping new items for numbers added to the range.

step will become negative (the range will be descending) if to is smaller than start. Range stops at to, it is not included in the range.

const [to, setTo] = createSignal(5);
const mapped = mapRange(
  () => 0,
  to,
  () => 0.5,
  number => {
    const [value, setValue] = createSignal(number);
    createEffect(
      () => value(),
      v => {
        /* react to value */
      },
    );
    return value;
  },
);
mapped(); // => [0, 0.5, 1, 1.5, 2...]
setTo(3); // changes the output array, mapping only added numbers

Definition

function mapRange<T>(
  start: Accessor<number>,
  to: Accessor<number>,
  step: Accessor<number>,
  mapFn: (n: number) => T,
  options?: {
    fallback?: Accessor<T>;
  },
): Accessor<T[]>;

<Range>

Creates a list of elements by mapping a number range of specified start, to, and step.

All start, to and step props are reactive, and changing them will cause the elements array to be recalculated, creating new elements for numbers added to the range.

• start defaults to 0.

• to defaults to 1. Range stops at to, it is not included in the range.

• step will become negative (the range will be descending) if to is smaller than start.

<Range start={2} to={14} step={0.5}>
   <div></div>
</Range>

// with a render prop:
<Range start={2} to={14} step={0.5}>
   {n => <div>{n}</div>}
</Range>

// with fallback:
<Range to={0}  fallback={<p>no items...</p>}>
   <div></div>
</Range>

Array spread shortcut:

const [start, setStart] = createSignal(0);
const [to, setTo] = createSignal(10);
const [step, setStep] = createSignal(2);

<Range {...[start, to, step]} />
<Range {...[0, 10, 2]} />
<Range start={start()} to={to()} step={step()} />

Definition

RangeProps is an interface of start, to and step props, OR 0, 1 and 2 indexes of a spread array.

function Range<T>(
  props: RangeProps & {
    fallback?: T;
    children: ((number: number) => T) | T;
  },
): Accessor<T[]>;

indexRange

Primitive for mapping a number range of specified start, to and step, while keeping previous elements of the same index. Underlying helper for the <IndexRange> control flow.

All start, to and step arguments are accessors, and changing them will cause the mapped array to be recalculated, mapping new items appended at the end of the range.

step will become negative (the range will be descending) if to is smaller than start. Range stops at to, it is not included in the range.

const [to, setTo] = createSignal(5);
const mapped = indexRange(
  () => 0,
  to,
  () => 0.5,
  number => {
    const [value, setValue] = createSignal(number());
    createEffect(
      () => number(),
      n => handleNewNumber(n),
    );
    return value;
  },
);
mapped(); // => [0, 0.5, 1, 1.5, 2...]
setTo(3); // changes the output array, mapping only added indexes

Definition

function indexRange<T>(
  start: Accessor<number>,
  to: Accessor<number>,
  step: Accessor<number>,
  mapFn: (n: Accessor<number>) => T,
  options?: {
    fallback?: Accessor<T>;
  },
): Accessor<T[]>;

<IndexRange>

Control Flow Component for displaying a number range of elements, where elements receive a number value as signal, by mapping a number range of specified start, to, and step.

All start, to and step props are reactive, and changing them will cause the elements array to be recalculated, creating new elements for numbers added to the range.

• start defaults to 0.

• to defaults to 1. Range stops at to, it is not included in the range.

• step will become negative (the range will be descending) if to is smaller than start.

<IndexRange start={2} to={14} step={0.5}>
   <div></div>
</IndexRange>

// with a render prop:
<IndexRange start={2} to={14} step={0.5}>
   {n => <div>{n()}</div>}
</IndexRange>

// with fallback:
<IndexRange to={0}  fallback={<p>no items...</p>}>
   <div></div>
</IndexRange>

Array spread shortcut:

const [start, setStart] = createSignal(0);
const [to, setTo] = createSignal(10);
const [step, setStep] = createSignal(2);

<IndexRange {...[start, to, step]} />
<IndexRange {...[0, 10, 2]} />
<IndexRange start={start()} to={to()} step={step()} />

Definition

RangeProps is an interface of start, to and step props, OR 0, 1 and 2 indexes of a spread array.

function IndexRange<T>(
  props: RangeProps & {
    fallback?: T;
    children: ((number: Accessor<number>) => T) | T;
  },
): Accessor<T[]>;

Possible improvements

(PRs Welcome)

• Currently the mapRange is handling decremanting ranges by swapping start and to with each other, and then cloning and reversing the mapped array. Doing this during the range mapping could possibly be more performant.
• For Ranges, because of how numbers are calculated, fractions might sometimes loose precision. E.g. a range from 1.64 to 2 by 0.2 step would generate numbers: [1.64, 1.8399999999999999] instead of [1.64, 1.84].
• Both mapRange and indexRange are missing index arguments in the mapping function.

Changelog

See CHANGELOG.md