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

recoil-form

v0.0.4

Published

Blazing fast React forms build on top of Recoil

Downloads

16

Readme

recoil-form: blazing fast React forms build on top of Recoil

Installation

npm install --save recoil-form recoil
// or
yarn add recoil-form recoil

Work in progress

This project is currently in "Work in progress" status

API and Usage

Form component

Use Form component as a main container for your form. This component creates a special form context, so all other components may only be used inside the Form component.

Props

initialValues: { [name: string]: any | Promise<any> }

Initial field values of the form. If promise is passed as an initial value of the field, then field is suspended until promise is resolved and resolved promise value will be used as a field value. See Field for more details.

onSubmit: (values, { setErrors, setValues, resetForm }) => void | Promise<void>

Your form submission handler. It is passed your forms values and special methods to change form state:

  • setErrors: ({ [name: string]: any }) => void – set form errors by passing errors object. Key is used as field name and value is used as an error value.
  • setErrors: (name: key, value: any, ...) => void – set form errors by passing name-value pairs
  • setValues: ({ [name: string]: any }) => void – set form values by passing values object (similar to initialValues).
  • setValues: (name: key, value: any, ...) => void – set form values by passing name-value pairs
  • resetForm: () => void – reset form to initial state (clear form values, errors and touched states)

Field component

Use Field component to add a new field to your form. Field component may represent default input or select components or any other custom component.

Props

name: string

Field name. The name is used as main field identifier and as a key in values object in onSubmit form handler.

type?: string

Field type. Used only if as property is not set. type defines which default underlying component will be used to represent the field. See supported types below.

value?: any

Field value. Used for checkbox and radio components. We do not use event.target.value internally, so you may use the value of any type. See more details below.

as: ElementType

React component which is used to render the field. Default is 'input'.

fallback: ReactNode

If you pass a Promise as a field value or initial value, this promise will be used with React.Suspense. Component will be suspended with fallback until promise is resolved. Once resolved, promise value will be used as field value or initial value.

Supported types

Default behaviour (as="input" or as={undefined} or missed as prop)

Renders default input field (except cases when type is "checkbox", "radio" or "file" which are described below)

  • name: string – the name of the field
  • defaultValue?: string - field's initial value
  • all other props except value are passed down to underlying input component. value is just ignored.
type="checkbox" (works only with as="input" or as={undefined} or missed as prop)

Renders default checkbox field.

  • name: string – the name of the field
  • value?: any - value used when checkbox checked. Default is true
  • uncheckedValue?: any - value used when checkbox unchecked. Default is undefined
  • defaultChecked?: boolean - if current checkbox checked or not. If defaultChecked={true} then initial value for the field set in Form.initialValues is always overridden with value.
  • all other props are passed down to underlying input component.
type="radio" (works only with as="input" or as={undefined} or missed as prop)

Renders default radio button.

  • name: string – the name of the field
  • value: any - value used when radio button checked.
  • defaultChecked?: boolean - if current radio button checked or not. If defaultChecked={true} then initial value for the field set in Form.initialValues is overridden with value. Keep in mind the case, when more than one radio button has defaultChecked={true}. In such case last rendered radio button will be checked and it's value will be used as an initial value for the field.
  • all other props are passed down to underlying input component.
type="file"

Not supported yet. WIP.

as="select"

Not supported yet. WIP.

Custom components via as={MyCustomComponent}

Not supported yet. WIP.

ErrorMessage component

Use ErrorMessage component to render error message related to the field. Error message is only shown for touched fields which has an truthy error value.

Props

name: string

The name of the field to which current error message is related.

as: ElementType

React component which is used to render the error message. Default is 'small'.

FieldArray component

Not ready yet. WIP

useForm hook

Not ready yet. WIP

useFormState hook

useFormState is a custom hook to retrieve current form state. Either 'ready' or 'submitting' is returned from this hook

Reference

useFormState(): 'ready' | 'submitting'

useFormValues hook

useFormValues is a custom hook to retrieve current form values.

Reference

useFormValues(): any

useField hook

useField is a custom React hook that will help you hook up inputs to recoil-form. You can use it to build your own custom input or input-related component.

Reference

useField<TValue = any>(name: string, initialValue?: string): [FieldInputProps<TValue>, FieldMetaProps, FieldHelperProps]

A custom React Hook that returns a 3-tuple (an array with three elements) containing FieldProps, FieldMetaProps and FieldHelperProps. It accepts a string of a field name and optional initialValue.

FieldInputProps<Value>
  • name: string - The name of the field
  • value: TValue - The field's value
  • onBlur: (event: React.FocusEvent) => void - A blur event handler
  • onChange: (event: React.ChangeEvent<any>) => void - A change event handler
FieldMetaProps<Value>

WIP

FieldHelperProps

An object that contains helper functions which you can use to imperatively change the value, error value or touched status for the field in question. This is useful for components which need to change a field's status directly, without triggering change or blur events.

  • setValue(value: any): void - A function to change the field's value
  • setTouched(value: boolean): void - A function to change the field's touched status
  • setError(value: any): void - A function to change the field's error value

useErrorMessage / useFieldError hook

useErrorMessage (or it's alias useFieldError) is a custom react hook that will allow you to get the field error. Your component will be automatically re-rendered when error is changed.

Reference

useFieldError<TValue = any>(name: string): TValue | null

useFieldValue hook

useFieldValue is a custom react hook that will allow you to get the current field value. Your component will be automatically re-rendered when value is changed.

useSetFieldError hook

useSetFieldError is a custom React hook that will allow you to get error updater function without subscription to field's error state.

useSetFieldValue hook

useSetFieldValue is a custom React hook that will allow you to get value updater function without subscription to field's value state.

License

MIT