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

kissmyform

v1.3.2

Published

a react hook to deal with forms

Downloads

6

Readme

Warning - DEPRECATED

I am deprecating this librery, because it has not worked well with a new scenario I run into, in which I needed the form to be spreaded in many tabs and components. I could have passed the functions and state from parents to children through properties but it did not felt right, and in this complex scenario I care about too many refreshes.

I will keep maintaining it as long as I stil use it a couple of places in production, but I won't use it in new projects and sooner or later those old projects will end or will be updated.

Kiss My Form

Kiss My Form is probably the most simple yet powerfull react form helper out there.

Demos and Examples

demo and examples

Hello-Word-ish Example

import useKMF from 'kissmyform'

exports default SomeFormComponent ({ onSubmit }) {
  const { inputControl, handleSubmit } = useKMF()

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...inputControl('username')} />
      <input {...inputControl('password')} type="password" />
      <button> Login </button>
    </form>
  )
}

API overview

useKMF (options) => helpers

React hook that help you manage the form.

options

  • afterChange(state) function that is called each after the form values is updated.
  • afterChangeDebounce If set, the afterChange function will be debounced this amount of miliseconds.
  • beforeChange({ context, errors, name, value, values }) function that is called before the form state is updated. valuesand errors can be mutated to change the update.
  • initialContext: object with the initial context of the form. Context are values that your form use to know how to behave, but it is not intended to be submited.
  • initialValues: object with the initial values of the form.

helpers

  • checkboxControl(name): sintactic sugar for name={name} checked={getValue(name)} onChange={setChecked}.
  • dispatch(newState): Updates the form state, computing isDirty and hasErrors, and calling afterChange.
  • getValue(name): returns the value of the form element whose name is name.
  • handleSubmit(callback): it calls callback when the form is submitted if there is no errors.
  • inputControl(name): sintactic sugar for name={name} value={getValue(name)} onChange={setInput}.
  • setChecked: handler for the onChange events of checkboxes that updates the state of the form.
  • setInput: handler for the onChange events of inputs, textareas and selects that updates the state of the form.
  • setValue(name, value): calls beforeUpdate and then updates the state of the form.
  • state: the state of the form { afterChange, context, errors, hasErrors, initialContext, initialValues, isDirty, values }.

Hook:

useKMF

 const { inputControl, handleSubmit } = useKMF()

useKMF is a react hook, it should be used like all the react hooks: it cannot be called conditionally and it only be called from inside components or hooks.

Options

afterChange(state) => undefined

 const { inputControl, handleSubmit } = useKMF({ afterChange })

It is called after any update of the form's state with the state as parameter.

Your component is supposed to be organized around reactivity, so everytime the you component funcion is called again, you check the state values and act accordingly. Buy you might want to pass an event handler from the component's parent. So it can change its state when the form has errors for instance. afterChange is meant for this.

beforeChange({ context, errors, name, value, values }) => undefined

 const { inputControl, handleSubmit } = useKMF({ beforeChange })

It is called before any update of the form's state with the state as parameter.

It is also called before submiting the form, once for each [name, value], and then all the changes you have made to values and errors are dispatches at once. You can use it to validate or transform the change.

initialValues

initialValues is one of the optional parameters that can be passed to useKMF.

It establishs the form's initial values at initialization time.

After form's initializaton, any change of initialValues could reload the component, but won't change its current values.

Helpers

`{...checkboxControl('name')}

it's a sintaxis-sugar helper that sets some values that the checkbox element to be managed.

It is equivalent to write name={name} value={getValue(name)} onChange={setChecked}.

dispatch({ context, errors, initialValues, values })

You can call dispatch to update the state of the form. All fields are optional, so if you want to update just the errors you can omit context, values and initialValues.

You could add isDirty and hasErrors, but that make no sense because those values are recomputed after aplying the new values.

dispatch will trigger afterChange. but it will not trigger beforeChange.

getValue(name) => string | boolean | any

It returns the value of the form element whose name is name.

You can also use state.values[name].

`onSubmit={handleSubmit(callback)}

It handles the onSubmit event of the form element.

It calls callback(values) if there is no errors.

If the callback function returns something falsy, it understands the forms has been submited so it sets initialValues to the current values and thus isDirty to false

If the callback function returns something truthy, it understands the forms has not submited,

{...inputControl(name)}

it's a sintaxis-sugar helper that sets some values that the checkbox element to be managed.

It is equivalent to write name={name} value={getValue(name)} onChange={setInput}.

onChange={setChecked}

It handles the onChange event for checkboxes.

onChange={setInput}

It handles the onChange event for inputs, textareas and selects.

setValue(name, value)

It calls beforeUpdate and then updates the state.

state

the state of the form has the following fields:

  • afterChange: The function set as afterChange in the options. You can change it with dispatch.
  • context: The object that helps the form to know how to behave, but are not errors or values.
  • initialValues: The object that holds the initial values, as you pass in within the options. You can change it with dispatch, but it will not affect the current values. It could affect isDirty though.
  • initialContext: The object that holds the initial context.
  • hasErrors: The ammount of values of the errors object. You cannot change it with dispath. It is computed by dispatch.
  • errors: It stores whatever errors you set with beforeChange. You can change it with dispatch, and it will affect hasErrors.
  • isDirty: Boolean that shows whether values is deeply equal to initialValues.
  • values: It store the values of your form. It is the parameter of the callback that handleSubmit calls. You can change it with dispatch.