# @cordelta/react-forms

> Ultra simple, stateless, validated forms for use in React function components

Latest version **0.0.12** (published 2021-06-04) · UNLICENSED license · 0 weekly downloads

## Install

```sh
npm install @cordelta/react-forms
pnpm add @cordelta/react-forms
yarn add @cordelta/react-forms
bun add @cordelta/react-forms
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.12 |
| Published | 2021-06-04 |
| First published | 2019-10-11 |
| Weekly downloads | 0 |
| License | UNLICENSED |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 64.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | danderson00 |
| Maintainers | seanwuapps, danderson00 |
| Keywords | react, stateless, form, function, component |

## Links

- npm: https://www.npmjs.com/package/@cordelta/react-forms
- Repository: https://github.com/cordeltadigital/react-forms
- Homepage: https://github.com/cordeltadigital/react-forms#readme
- Issues: https://github.com/cordeltadigital/react-forms/issues
- npm.io page: https://npm.io/package/@cordelta/react-forms

## Dependencies (1)

- [object-path-immutable](https://npm.io/package/object-path-immutable.md) ^4.1.1

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.0.12 (latest) — 2021-06-04
- 0.0.11 — 2021-06-04
- 0.0.10 — 2021-06-04
- 0.0.9 — 2020-09-05
- 0.0.8 — 2020-09-05
- 0.0.7 — 2020-09-05
- 0.0.6 — 2020-09-05
- 0.0.5 — 2020-03-02
- 0.0.4 — 2020-02-25
- 0.0.3 — 2020-02-17
- 0.0.2 — 2019-10-12
- 0.0.1 — 2019-10-11

## README

# @cordelta/react-forms

Ultra simple, stateless, validated forms for use in React function components.

## Installation

```shell
yarn add @cordelta/react-forms
```
    
## Usage

```jsx
import React from 'react'
import { Form, Input, Textarea, Select, Submit } from '@cordelta/react-forms'

export default ({ onSubmit, onCancel, initialValues }) => (
  <Form onSubmit={onSubmit} values={initialValues}>
    <label>Name</label>
    <Input name="name" required minLength="5" maxLength="50" />

    <label>Description</label>
    <Textarea name="description" maxLength="100" />

    <label>Type</label>
    <Select name="type" options={['', 'Widget', 'Component']} required />

    <label>Rating</label>
    <div>
      <Input name="rating" type="radio" numeric value="1" checked />
      <Input name="rating" type="radio" numeric value="2" />
      <Input name="rating" type="radio" numeric value="3" />
    </div>

    <label>Urgent</label>
    <Input name="urgent" type="checkbox" />

    <div>
      <Submit>Submit</Submit>
      <button onClick={onCancel}>Cancel</button>
    </div>
  </Form>
)
```

All `props` passed to components are passed to underlying HTML elements. Standard HTML `option` elements can also be
used for specifying options for the `Select` component. Using `type="number"` or adding a `numeric` prop will coerce 
the provided value to a `Number` type. Specifying a `value` prop for checkboxes causes the output value to toggle 
between the provided value and `undefined`.

Form `onSubmit` handlers are passed an object containing form values:

```json
{
  "name": "",
  "description": "",
  "type": "",
  "rating": 1,
  "urgent": false
}
```

The `onSubmit` handler passed to the `Form` component is only called if validation passes. Form submission is also 
triggered when the `Enter` key (or `Go` button on mobile) is pressed while form elements are active.

### Deep Object Structures

Simple dotted notation can be used to create deep object structures:

```jsx
<Form>
  <Input name="name" />
  <Input name="inventory.stockLevel" type="number" />
  <Input name="inventory.quantityOnOrder" type="number" />
  <Submit onSubmit={values => console.log(values)} />
</Form>
```

```json
{
  "name": "",
  "inventory": {
    "stockLevel": 0,
    "quantityOnOrder": 0
  }
}
```

### Styling

No styling is provided out of the box. Default corresponding HTML elements are used and can be directly styled using 
CSS or style attributes.

Additionally, a `validated` class is applied to individual elements as they change, and to the form when it is
submitted. This allows you to make use of the `:invalid` CSS pseudo-class, but only display validation styles after
validation has occurred.

Styling to work with the example code above might look something like:

```css
form > * {
  display: block;
}

form label {
  font-size: 0.8em;
}

form label:not(:first-child) {
  margin-top: 5px;
}

form .validated:invalid {
  outline: 1px solid red;
}
```

## Custom Components

`react-functional-forms` exposes functions that can be used to wrap components so that they can be included in output 
form value objects.

```jsx
import React from 'react'
import { wrapInput, wrapSubmit, Form } from '@cordelta/react-forms'

const InputField = wrapInput(({ label, className, ...inputProps }) =>
  <div className={className}>
    <label>{label}</label>
    <input {...inputProps} />
  </div>
)

const AnchorSubmit = wrapSubmit(props => <a {...props} />) 

export const SampleForm = ({ onSubmit }) => (
  <Form onSubmit={onSubmit}>
    <InputField label="Name" name="name" required />
    <InputField label="Description" name="description" maxLength="100" />
    <InputField label="Urgent" name="urgent" type="checkbox" />
    <AnchorSubmit>Submit</AnchorSubmit>
  </Form>
)
```

The `wrapInput` function manages the `value` and `onChange` props and in most cases, these are the only props you
need to pass to your input component. In the example above, all other props are also passed on to enable validation.

If your custom component is rendered with a `type` prop of `radio` or `checkbox`, this will cause the `checked` prop
to become managed instead of `value`, and should be passed to your input component. You can also force the component
to be treated as a radio button or checkbox by specifying options to the `wrapInput` function. More on this below.

The `wrapSubmit` function manages the `onClick` and `disabled` props of your submit component. All other props can be
safely ignored or passed on.

### Integration With Third Party Libraries

The functions described above can also be used to easily wrap components from third party libraries.

```jsx
import { wrapInput } from 'react-functional-forms'
import * as material from '@material-ui/core'

export const Input = wrapInput(material.Input)
export const Checkbox = wrapInput(material.Checkbox, { type: 'checkbox' })
export const Radio = wrapInput(material.Radio, { type: 'radio' })
export const Select = wrapInput(material.Select, { type: 'select' })
export const Switch = wrapInput(material.Switch, { type: 'checkbox' })
```

## API

### wrapInput(component, options)

Options are as follows:

Option|Type|Default|Description
-|-|-|-
type|string|'text'|One of `text`, `radio`, `checkbox` or `select`.
passErrorProp|boolean|false|Passes a boolean prop named `error` when field validation fails.
valueFromEvent|function||Override the default mechanism for retrieving a new field value from an onChange event. All function arguments are passed on.
defaultValue|any||Specify the default value for the field. Can be a value or a function that returns a value. 

### wrapSubmit(component)

---
_Source: https://npm.io/package/@cordelta/react-forms · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._