Purely functional two-way data binding and form validation for React
npm install @linked/react!logo
useState React Hook on steroids providing an elegant callback-free solution for complex forms with input validation and making the React state a perfect state container. It's lightweight (6.5K minified) and designed to be used with both JS and TypeScript.
Link is the object representing the writable reference to the member of the component's state encapsulating the value, function to update the value, and the validation error. Link class has a set of methods to perform useful transformations, such as $link.props generating the pair of standard { value, onChange } props.
NestedLink dramatically improves your React project's modularity and code readability.
javascript
import { useLink } from '@linked/react'
import { MyInput } from './controls.jsx'
const coolState = { some : { name : '' } };
const MyCoolComponent = () => {
// Digging through the object to get a link to the coolState.some.name
const $name = useLink( coolState ).at( 'some' ).at( 'name' )
// applying the validation rules
$name.check( x => x.length > 0, 'Name is required' ),
.check( x => x.length > 2, 'Name is too short' );
.check( x => x.length < 20, 'Name is too long' );
return (
)
}
// controls.jsx
import * as React from 'react'
// Custom form field with validation taking the link to the value
const MyInput = ({ $value }) => (
{ $value.error || '' }
)
`
Features
IMPORTANT! Version 2.x is not entirely backwards compatible with 1.x, see the release notes at the bottom.
- Callback-free form controls binding to the component state.
- Complete separation of the validation logic from the markup.
- Easy handling of nested objects and arrays in the component state.
- Complete support for the React Hooks API and functional components.
- Pricise TypeScript typings.
Reference implementation of 'linked' UI controls (optional linked-controls npm package):
- Standard tags: , , ,
- Custom tags: , ,
- Validator functions: isNumber, isEmail, isRequred.
Tutorials
The rationale behind the design and a high-level overview of how amazing NestedLink is: React Hooks, form validation, and complex state
The series of 5-minute tutorials (with React.Component):
- The basics of ValueLink design pattern
- Form validation with ValueLinks
- Complex state with ValueLinks
$3
$3
$3
How to
$3
There are no side dependencies except react as peer dependency. Installation:
npm install valuelink --save-dev
Usage with React Hooks (check out the React Hooks starting boilerplate).
`javascript
import React from 'react'
import { useLink } from '@linked/react'
...
// Instead of const [ name, setName ] = useState('')
const $name = useLink('');
`
Usage with React Component.
`javascript
import React from 'react'
// Instead of React.Component...
import { LinkedComponent } from '@linked/react'
...
// In a render, do
const $name = this.$at('name');
// Or, to link all the state members at once...
const state$ = this.state$();
`
Refer to the databinding examples and the manual for the typical data binding scenarios.
$3
Use linked-controls project as the starting boilerplate for your components.
$3
NestedLink is an abstraction of the data binding independent on both the particular control and the state container. The default binding implemented
in the library is for the standard React state. It's fairly easy to create your own.
You need to subclass React.Component and make your own $at and state$ methods.
You can either use Link.value inside to create links dynamically, or extend the Link as it's done in /valuelink/src/component.ts.
$3
!design
It's a very simple library written with TypeScript, there's no any magic inside (except some scary type annotations). If you want to play with the examples, fix the bug, or whatever:
yarn - installs the dependencies.
yarn build - compiles everything including examples.
Release Notes
$3
- IMPORTANT: Repository is converted to the monorepository based on yarn worspaces.
- IMPORTANT: valuelink/tags.jsx is moved to the dedicated package linked-controls.
- Complete support of new React Hooks API.
- useLink() to create the state link.
- useIO() to perform promised IO on mount.
- useLocalStorage() to persist links to the local storage (loaded on mount, saved on unmount).
- $-notation for the link variables.
- New React.Component API (this.linkAt -> this.$at, this.linkAll -> this.state$)
- Group operations Link.getValues(), Link.setValues(), Link.getErrors()
$3
React Hooks support.
- useLink( initValue ) - create linked state.
- setLinks({ lnk1, lnk2, ... }, json ) - bulk set link values from an object.
- linksValues({ lnk1, lnk2, ... }) - extract values object from links.
- linksErrors({ lnk1, lnk2, ... }) - extract errors object from links.
$3
- can be used to bind the link to any of the standard controls expecting value and onChange` props.