# @natural-forms/input

> Unstyled input component with built-in validation.

Latest version **1.0.10** (published 2022-05-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install @natural-forms/input
pnpm add @natural-forms/input
yarn add @natural-forms/input
bun add @natural-forms/input
```

## Health

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

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.10 |
| Published | 2022-05-04 |
| First published | 2022-02-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 36.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Douglas Moura |
| Maintainers | douglasdemoura |

## Links

- npm: https://www.npmjs.com/package/@natural-forms/input
- Repository: https://github.com/DouglasdeMoura/natural-forms
- Homepage: https://github.com/DouglasdeMoura/natural-forms#readme
- Issues: https://github.com/DouglasdeMoura/natural-forms/issues
- npm.io page: https://npm.io/package/@natural-forms/input

## Dependencies (4)

- [react](https://npm.io/package/react.md) ^17.0.2
- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [react-dom](https://npm.io/package/react-dom.md) ^17.0.2
- [@react-hook/merged-ref](https://npm.io/package/@react-hook/merged-ref.md) ^1.3.2

## Recent versions

- 1.0.10 (latest) — 2022-05-04
- 1.0.9 — 2022-05-04
- 1.0.8 — 2022-03-02
- 1.0.7 — 2022-02-22
- 1.0.6 — 2022-02-22
- 1.0.5 — 2022-02-22
- 1.0.4 — 2022-02-22
- 1.0.3 — 2022-02-22
- 1.0.2 — 2022-02-22
- 1.0.1 — 2022-02-22
- 1.0.0 — 2022-02-21

## README

# Input

A input component with built-in validation that fires on the [`blur`](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event)
event.

## Features

- Input validation that uses the [`ValidityState`](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) interface;
- Custom validation using a validator function passed to the `custom` prop;
- Applies a mask to the input using a custom function passed to the `mask` prop;
- Fires a `onError` event when the input is invalid;
- Fires a `onValidate` event when the input is valid;
- Input's `name` and `id` attributes are automatically generated when not provided;
- Compatible with any styling mwthod, as it exposes the HTML elements directly.

## Installation

Install with your preferred package manager:

```
npm install @natural-forms/input
```

or

```
yarn add @natural-forms/input
```

## Anatomy

```tsx
import * as InputPrimitive from '@natural-forms/input'

export default () => {
  <InputPrimitive.Root>
    <InputPrimitive.Label />
    <InputPrimitive.Input />
    <InputPrimitive.Error />
  </InputPrimitive.Root>
}
```

Please refer to the [tests](https://github.com/DouglasdeMoura/natural-forms/blob/main/packages/input/src/input.spec.tsx) file
in order to se a more complete example.

## API reference

### Root

The `div` element that should wrap the input, label and error components,
in order to provide the context that shared the `input`'s id with the `label`.

Accepts all props of a `div` element.

### Label

The `label` element that should be used to describe the input. Its text is used
to generate the `input`'s `id` and `name` attributes.

Accepts all props of a `label` element.

### Input

The `input` element that should be used to capture the user's input. If no `id`
is provided, "camelcasify" the `label`'s text and use it as the `id` attribute.
If no `name` is provided, use the `id` attribute.

Besides the props of the `input` element, it accepts the following props:

- `onError`: receives a function that is called when the input is invalid, which receives the current input value and the list of erros;
- `onValidate`: receives a function that is called when the input is valid;
- `custom`: receives a custom validation function that will be applied to the stack of validators;
- `mask`: receives a function that applies a mask to the input's value.

### Error

A `p` element that shows the first error message from the list of errors.

## Styling

When the data is invalid, all the elemente receive an attribute `data-invalid`
with the value `true`. Therefore, you will be able to style all the elements
like the example below:

```css
[data-invalid="true"] {
  color: red;
}
```

The error message container element has a `data-error` attribute. Therefore,
you can style it like the example below:

```css
[data-error] {
  color: red;
}
```

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