API Reference

August 6, 2018 · View on GitHub

Components
Connected Components

`<Value>`

The <Value> component is the most generic component exposed by react-values, and it is the base for all other components.

It takes either a value or defaultValue and an onChange handler. Depending on whether you pass it value or defaultValue it will either be "controlled" or "uncontrolled", respectively.

<Value
  value={Any|undefined}
  defaultValue={Any|undefined}
  onChange={Function}
  disabled={Boolean}
>
  {({
    value,
    set,
    clear,
    reset,
  }) => (
    ...
  )}
</Value>

Prop	Type	Description
`value`	`Any`	The value, for controlled components.
`defaultValue`	`Any`	The default value, for uncontrolled components.
`onChange`	`Function` `onChange(value)`	A handler that will be called whenever the current value changes.
`disabled`	`Boolean`	Whether the component is current disabled, ignoring state changes.

Render Prop	Type	Description
`value`	`Any`	The state's current value.
`disabled`	`Boolean`	Whether the component is currently disabled or not.
`set`	`Function` `set(value)`	Sets the value to a new state.
`clear`	`Function` `clear()`	Sets the value to `undefined`.
`reset`	`Function` `reset()`	Resets the value to its initial `value/defaultValue` state.

`<ArrayValue>`

A value for an Array.

<ArrayValue
  value={Array|undefined}
  defaultValue={Array|undefined}
  onChange={Function}
  disabled={Boolean}
>
  {({
    value,
    set,
    reset,
    concat,
    fill,
    filter,
    map,
    pop,
    push,
    reverse,
    shift,
    slice,
    sort,
    splice,
    unshift,
  }) => (
    ...
  )}
</ArrayValue>

Prop	Type	Description
`value`	`Any`	The value, for controlled components.
`defaultValue`	`Any`	The default value, for uncontrolled components.
`onChange`	`Function` `onChange(value)`	A handler that will be called whenever the current value changes.
`disabled`	`Boolean`	Whether the component is current disabled, ignoring state changes.

Render Prop	Type	Description
`value`	`Array`	The current array value.
`disabled`	`Boolean`	Whether the component is currently disabled or not.
`set`	`Function` `set(array)`	Sets the value to a new state.
`clear`	`Function` `clear()`	Sets the value to an `[]` empty array.
`reset`	`Function` `reset()`	Resets the value to its initial `value/defaultValue` state.
`first`	`Any`	The first element in the current array value.
`last`	`Any`	The last element in the current array value.
`concat`	`Function` `concat(...values)`	Calls `Array.concat`.
`fill`	`Function` `fill(value)`	Calls `Array.fill`.
`filter`	`Function` `filter(callback)`	Calls `Array.filter`.
`flat`	`Function` `flat(depth)`	Calls `Array.flat`.
`flatMap`	`Function` `flatMap(callback)`	Calls `Array.flatMap`.
`map`	`Function` `map(callback)`	Calls `Array.map`.
`pop`	`Function` `pop()`	Calls `Array.pop`.
`push`	`Function` `push(...values)`	Calls `Array.push`.
`reverse`	`Function` `reverse()`	Calls `Array.reverse`.
`shift`	`Function` `shift()`	Calls `Array.shift`.
`slice`	`Function` `slice(begin, end)`	Calls `Array.slice`.
`sort`	`Function` `sort(comparator)`	Calls `Array.sort`.
`splice`	`Function` `splice(start, remove, ...values)`	Calls `Array.splice`.
`unshift`	`Function` `unshift(...values)`	Calls `Array.unshift`.

`<BooleanValue>`

A value for a Boolean.

<BooleanValue
  value={Boolean|undefined}
  defaultValue={Boolean|undefined}
  onChange={Function}
  disabled={Boolean}
>
  {({
    value,
    set,
    clear,
    reset,
    toggle,
  }) => (
    ...
  )}
</BooleanValue>

Prop	Type	Description
`value`	`Any`	The value, for controlled components.
`defaultValue`	`Any`	The default value, for uncontrolled components.
`onChange`	`Function` `onChange(value)`	A handler that will be called whenever the current value changes.
`disabled`	`Boolean`	Whether the component is current disabled, ignoring state changes.

Render Prop	Type	Description
`value`	`Boolean`	The current boolean value.
`disabled`	`Boolean`	Whether the component is currently disabled or not.
`set`	`Function` `set(boolean)`	Sets the value to a new state.
`clear`	`Function` `clear()`	Sets the value to `false`.
`reset`	`Function` `reset()`	Resets the value to its initial `value/defaultValue` state.
`toggle`	`Function` `toggle()`	Sets the boolean to its opposite value.

`<DateValue>`

A value for a Date.

<DateValue
  value={Date|undefined}
  defaultValue={Date|undefined}
  onChange={Function}
  disabled={Boolean}
>
  {({
    value,
    set,
    clear,
    reset,
    date,
    hours,
    milliseconds,
    minutes,
    month,
    seconds,
    year,
    setDate,
    setHours,
    setMilliseconds,
    setMinutes,
    setMonth,
    setSeconds,
    setYear,
    incrementDate,
    incrementHours,
    incrementMilliseconds,
    incrementMinutes,
    incrementMonth,
    incrementSeconds,
    incrementYear,
    decrementDate,
    decrementFullYear,
    decrementHours,
    decrementMilliseconds,
    decrementMinutes,
    decrementMonth,
    decrementSeconds,
  }) => (
    ...
  )}
</DateValue>

Prop	Type	Description
`value`	`Any`	The value, for controlled components.
`defaultValue`	`Any`	The default value, for uncontrolled components.
`onChange`	`Function` `onChange(value)`	A handler that will be called whenever the current value changes.
`disabled`	`Boolean`	Whether the component is current disabled, ignoring state changes.

Render Prop	Type	Description
`value`	`Date`	The current date value.
`disabled`	`Boolean`	Whether the component is currently disabled or not.
`set`	`Function` `set(date)`	Sets the value to a date.
`clear`	`Function` `clear()`	Sets the value to `new Date()`.
`reset`	`Function` `reset()`	Resets the value to its initial `value/defaultValue` state.
`year`	`Number`	The current state of `value.getFullYear()`.
`month`	`Number`	The current state of `value.getMonth()`.
`date`	`Number`	The current state of `value.getDate()`.
`hours`	`Number`	The current state of `value.getHours()`.
`minutes`	`Number`	The current state of `value.getMinutes()`.
`seconds`	`Number`	The current state of `value.getSeconds()`.
`milliseconds`	`Number`	The current state of `value.getMilliseconds()`.
`setYear`	`Function` `setYear(n)`	Calls `Date.setFullYear`.
`setMonth`	`Function` `setMonth(n)`	Calls a bug-fixed version of `Date.setMonth`.
`setDate`	`Function` `setDate(n)`	Calls `Date.setDate`.
`setHours`	`Function` `setHours(n)`	Calls `Date.setHours`.
`setMinutes`	`Function` `setMinutes(n)`	Calls `Date.setMinutes`.
`setSeconds`	`Function` `setSeconds(n)`	Calls `Date.setSeconds`.
`setMilliseconds`	`Function` `setMilliseconds(n)`	Calls `Date.setMilliseconds`.
`incrementYear`	`Function` `incrementYear(n = 1)`	Increments the value's year by `n`.
`incrementMonth`	`Function` `incrementMonth(n = 1)`	Increments the value's month by `n`.
`incrementDate`	`Function` `incrementDate(n = 1)`	Increments the value's date by `n`.
`incrementHours`	`Function` `incrementHours(n = 1)`	Increments the value's hours by `n`.
`incrementMinutes`	`Function` `incrementMinutes(n = 1)`	Increments the value's minutes by `n`.
`incrementSeconds`	`Function` `incrementSeconds(n = 1)`	Increments the value's seconds by `n`.
`incrementMilliseconds`	`Function` `incrementMilliseconds(n = 1)`	Increments the value's milliseconds by `n`.
`decrementYear`	`Function` `decrementYear(n = 1)`	Decrements the value's year by `n`.
`decrementMonth`	`Function` `decrementMonth(n = 1)`	Decrements the value's month by `n`.
`decrementDate`	`Function` `decrementDate(n = 1)`	Decrements the value's date by `n`.
`decrementHours`	`Function` `decrementHours(n = 1)`	Decrements the value's hours by `n`.
`decrementMinutes`	`Function` `decrementMinutes(n = 1)`	Decrements the value's minutes by `n`.
`decrementSeconds`	`Function` `decrementSeconds(n = 1)`	Decrements the value's seconds by `n`.
`decrementMilliseconds`	`Function` `decrementMilliseconds(n = 1)`	Decrements the value's milliseconds by `n`.

`<MapValue>`

A value for a Map.

<MapValue
  value={Map|undefined}
  defaultValue={Map|undefined}
  onChange={Function}
  disabled={Boolean}
>
  {({
    value,
    set,
    clear,
    reset,
    unset,
    delete,
  }) => (
    ...
  )}
</MapValue>

Prop	Type	Description
`value`	`Any`	The value, for controlled components.
`defaultValue`	`Any`	The default value, for uncontrolled components.
`onChange`	`Function` `onChange(value)`	A handler that will be called whenever the current value changes.
`disabled`	`Boolean`	Whether the component is current disabled, ignoring state changes.

Render Prop	Type	Description
`value`	`Any`	The current map value.
`disabled`	`Boolean`	Whether the component is currently disabled or not.
`set`	`Function` `set(key, value)` or `set(map)`	Calls `Map.set`, or sets the value to a new map.
`clear`	`Function` `clear()`	Calls `Map.clear`.
`reset`	`Function` `reset()`	Resets the value to its initial `value/defaultValue` state.
`delete`	`Function` `delete(key)`	Calls `Map.delete`.
`unset`	`Function` `unset(key)`	An alias for `Map.delete` that's not a reserved word.

`<NumberValue>`

A value for a Number.

<NumberValue
  value={Number|undefined}
  defaultValue={Number|undefined}
  onChange={Function}
  disabled={Boolean}
  min={Number|undefined}
  max={Number|undefined}
>
  {({
    value,
    set,
    reset,
    increment,
    decrement,
  }) => (
    ...
  )}
</NumberValue>

Prop	Type	Description
`value`	`Any`	The value, for controlled components.
`defaultValue`	`Any`	The default value, for uncontrolled components.
`onChange`	`Function` `onChange(value)`	A handler that will be called whenever the current value changes.
`disabled`	`Boolean`	Whether the component is current disabled, ignoring state changes.
`min`	`Number`	An optional minimum value to not go under.
`max`	`Number`	An optional maximum value to not go over.

Render Prop	Type	Description
`value`	`Number`	The current number value.
`disabled`	`Boolean`	Whether the component is currently disabled or not.
`set`	`Function` `set(number)`	Sets the value to a new `number`.
`clear`	`Function` `clear()`	Sets the value to `0`.
`reset`	`Function` `reset()`	Resets the value to its initial `value/defaultValue` state.
`increment`	`Function` `increment(n = 1)`	Increments the number by `n`.
`decrement`	`Function` `decrement(n = 1)`	Decrements the number by `n`.

`<ObjectValue>`

A value for a Object.

<ObjectValue
  value={Object|undefined}
  defaultValue={Object|undefined}
  onChange={Function}
  disabled={Boolean}
>
  {({
    value,
    set,
    clear,
    reset,
    unset,
    delete,
    assign,
  }) => (
    ...
  )}
</ObjectValue>

Prop	Type	Description
`value`	`Any`	The value, for controlled components.
`defaultValue`	`Any`	The default value, for uncontrolled components.
`onChange`	`Function` `onChange(value)`	A handler that will be called whenever the current value changes.
`disabled`	`Boolean`	Whether the component is current disabled, ignoring state changes.

Render Prop	Type	Description
`value`	`Any`	The current object value.
`disabled`	`Boolean`	Whether the component is currently disabled or not.
`set`	`Function` `set(key, value)` or `set(object)`	Set a specific `key` in to `value`, or sets the value to a new object.
`clear`	`Function` `clear()`	Set the value to a new empty object.
`reset`	`Function` `reset()`	Resets the value to its initial `value/defaultValue` state.
`delete`	`Function` `delete(key)`	Delete a key from the current object.
`unset`	`Function` `unset(key)`	An alias for `delete` that's not a reserved word.
`assign`	`Function` `assign(value)`	Extend the current object with another value using `Object.assign`.

`<SetValue>`

A value for a Set.

<SetValue
  value={Set|undefined}
  defaultValue={Set|undefined}
  onChange={Function}
  disabled={Boolean}
>
  {({
    value,
    set,
    clear,
    reset,
    add,
    remove,
    delete,
    toggle,
  }) => (
    ...
  )}
</SetValue>

Prop	Type	Description
`value`	`Any`	The value, for controlled components.
`defaultValue`	`Any`	The default value, for uncontrolled components.
`onChange`	`Function` `onChange(value)`	A handler that will be called whenever the current value changes.
`disabled`	`Boolean`	Whether the component is current disabled, ignoring state changes.

Render Prop	Type	Description
`value`	`Set`	The current set value.
`disabled`	`Boolean`	Whether the component is currently disabled or not.
`set`	`Function` `set(set)`	Sets the value to a new `set`.
`clear`	`Function` `clear()`	Calls `Set.clear`.
`reset`	`Function` `reset()`	Resets the value to its initial `value/defaultValue` state.
`add`	`Function` `add(value)`	Calls `Set.add`.
`delete`	`Function` `delete(value)`	Calls `Set.delete`.
`remove`	`Function` `remove(value)`	An alias for `Set.delete` that's not a reserved word.
`toggle`	`Function` `toggle(value, boolean)`	Add or remove a `value` based on a `boolean`.

`<StringValue>`

A value for a String.

<StringValue
  value={String|undefined}
  defaultValue={String|undefined}
  onChange={Function}
  disabled={Boolean}
>
  {({
    value,
    set,
    clear,
    reset,
    concat,
    padEnd,
    padStart,
    repeat,
    replace,
    slice,
    substr,
    substring,
    toLowerCase,
    toUpperCase,
    trim,
    trimEnd,
    trimStart,
  }) => (
    ...
  )}
</StringValue>

Prop	Type	Description
`value`	`Any`	The value, for controlled components.
`defaultValue`	`Any`	The default value, for uncontrolled components.
`onChange`	`Function` `onChange(value)`	A handler that will be called whenever the current value changes.
`disabled`	`Boolean`	Whether the component is current disabled, ignoring state changes.

Render Prop	Type	Description
`value`	`String`	The current string value.
`disabled`	`Boolean`	Whether the component is currently disabled or not.
`set`	`Function` `set(string)`	Sets the value to a new `string`.
`clear`	`Function` `clear()`	Sets the value to an `''` empty string.
`reset`	`Function` `reset()`	Resets the value to its initial `value/defaultValue` state.
`concat`	`Function` `concat(value)`	Calls `String.concat`.
`padEnd`	`Function` `padEnd(value)`	Calls `String.padEnd`.
`padStart`	`Function` `padStart(value)`	Calls `String.padStart`.
`repeat`	`Function` `repeat(value)`	Calls `String.repeat`.
`replace`	`Function` `replace(value)`	Calls `String.replace`.
`slice`	`Function` `slice(value)`	Calls `String.slice`.
`substr`	`Function` `substr(value)`	Calls `String.substr`.
`substring`	`Function` `substring(value)`	Calls `String.substring`.
`toLowerCase`	`Function` `toLowerCase(value)`	Calls `String.toLowerCase`.
`toUpperCase`	`Function` `toUpperCase(value)`	Calls `String.toUpperCase`.
`trim`	`Function` `trim(value)`	Calls `String.trim`.
`trimEnd`	`Function` `trimEnd(value)`	Calls `String.trimEnd`.
`trimStart`	`Function` `trimStart(value)`	Calls `String.trimStart`.

`createValue`

The createValue factory creates a new <Value> component with the exact same API, but that shares its state between multiple places in your app's render tree.

It takes either a defaultValue and an optional set of defaultProps, and returns a React component. The ConnectedValue constructor also has all of the transforms exposed as static methods, so you can update the connected value without even rendering it.

const ConnectedValue = createValue('default')

<ConnectedValue>
  {({ value, ... }) => (
    ...
  )}
</ConnectedValue>

Argument	Type	Description
`defaultValue`	`Any`	The default connected value.
`defaultProps`	`Object`	An optional set of default props.

`createArrayValue`

Create a connected <ArrayValue> component.

const ConnectedArrayValue = createArrayValue([0, 1, 2])

<ConnectedArrayValue>
  {({ value, push, pop, slice, ... }) => (
    ...
  )}
</ConnectedArrayValue>

Argument	Type	Description
`defaultValue`	`Array`	The default connected value.
`defaultProps`	`Object`	An optional set of default props.

`createBooleanValue`

Create a connected <BooleanValue> component.

const ConnectedBooleanValue = createBooleanValue(true)

<ConnectedBooleanValue>
  {({ value, set, toggle, ... }) => (
    ...
  )}
</ConnectedBooleanValue>

Argument	Type	Description
`defaultValue`	`Boolean`	The default connected value.
`defaultProps`	`Object`	An optional set of default props.

`createDateValue`

Create a connected <DateValue> component.

const ConnectedDateValue = createDateValue(new Date())

<ConnectedDateValue>
  {({ value, date, month, year, ... }) => (
    ...
  )}
</ConnectedDateValue>

Argument	Type	Description
`defaultValue`	`Date`	The default connected value.
`defaultProps`	`Object`	An optional set of default props.

`createMapValue`

Create a connected <MapValue> component.

const ConnectedMapValue = createMapValue(new Map([['a', 1]]))

<ConnectedMapValue>
  {({ value, set, unset, ... }) => (
    ...
  )}
</ConnectedMapValue>

Argument	Type	Description
`defaultValue`	`Map`	The default connected value.
`defaultProps`	`Object`	An optional set of default props.

`createNumberValue`

Create a connected <NumberValue> component.

const ConnectedNumberValue = createNumberValue(42)

<ConnectedNumberValue>
  {({ value, increment, decrement, ... }) => (
    ...
  )}
</ConnectedNumberValue>

Argument	Type	Description
`defaultValue`	`Number`	The default connected value.
`defaultProps`	`Object`	An optional set of default props.

`createObjectValue`

Create a connected <ObjectValue> component.

const ConnectedObjectValue = createObjectValue({ a: 1 })

<ConnectedObjectValue>
  {({ value, set, unset, ... }) => (
    ...
  )}
</ConnectedObjectValue>

Argument	Type	Description
`defaultValue`	`Object`	The default connected value.
`defaultProps`	`Object`	An optional set of default props.

`createSetValue`

Create a connected <SetValue> component.

const ConnectedSetValue = createSetValue(new Set([0, 1, 2]))

<ConnectedSetValue>
  {({ value, add, remove, ... }) => (
    ...
  )}
</ConnectedSetValue>

Argument	Type	Description
`defaultValue`	`Set`	The default connected value.
`defaultProps`	`Object`	An optional set of default props.

`createStringValue`

Create a connected <StringValue> component.

const ConnectedStringValue = createStringValue('default')

<ConnectedStringValue>
  {({ value, repeat, slice, ... }) => (
    ...
  )}
</ConnectedStringValue>

Argument	Type	Description
`defaultValue`	`String`	The default connected value.
`defaultProps`	`Object`	An optional set of default props.