react-magical-form

Attention

This package is published as ES Modules, so please use a bundler such as Webpack.

Installation

npm install -S react-magical-form

yarn add react-magical-form

Basic Usage

import React from 'react';
import { checkbox, number, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { field, handleSubmit } = useForm({
    name: text(),
    age: number(),
    acceptsPolicy: checkbox(),
  });

  return (
    <form
      onSubmit={handleSubmit((values) => {
        // Do something
      })}
    >
      <div>
        <input ref={field('name')} type="text" />
      </div>

      <div>
        <input ref={field('age')} type="number" />
      </div>

      <div>
        <input ref={field('acceptsPolicy')} type="checkbox" />
      </div>

      <button type="submit">Submit</button>
    </form>
  );
};

Supported field types

`text()`

Results in string.

import React from 'react';
import { text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { field, getValues } = useForm({
    foo: text({ initial: '' }),
  });

  getValues().foo; //=> string

  return <input ref={field('foo')} type="text" />;
};

`number()`

Results in number | undefined.

import React from 'react';
import { number, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { field, getValues } = useForm({
    foo: number({ initial: undefined }),
  });

  getValues().foo; //=> number | undefined

  return <input ref={field('foo')} type="number" />;
};

`checkbox()`

Results in boolean.

import React from 'react';
import { checkbox, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { field, getValues } = useForm({
    foo: checkbox({ initial: false }),
  });

  getValues().foo; //=> boolean

  return <input ref={field('foo')} type="checkbox" />;
};

`textChoice()`

Results in string | undefined.

import React from 'react';
import { textChoice, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { field, getValues } = useForm({
    foo: textChoice({ initial: undefined }),
  });

  getValues().foo; //=> string | undefined

  return (
    <>
      <input ref={field('foo')} type="radio" name="foo" value="bar" />
      {/*                       ^^^^^^^^^^^^
                                `type` property is required and it should be "radio".
      */}
      <input ref={field('foo')} type="radio" name="foo" value="baz" />
      {/*                                    ^^^^^^^^^^
                                             `name` property is required
                                               with the same value of field name.
      */}
    </>;
  );
};

`numberChoice()`

Results in number | undefined.

import React from 'react';
import { numberChoice, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { field, getValues } = useForm({
    foo: numberChoice({ initial: undefined }),
  });

  getValues().foo; //=> number | undefined

  return (
    <>
      <input ref={field('foo')} type="radio" name="foo" value="0" />
      {/*                       ^^^^^^^^^^^^
                                `type` property is required and it should be "radio".
      */}
      <input ref={field('foo')} type="radio" name="foo" value="1" />
      {/*                                    ^^^^^^^^^^
                                             `name` property is required
                                               with the same value of field name.
      */}
    </>;
  );
};

`file()`

Results in File | undefined.

import React from 'react';
import { file, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { field, getValues } = useForm({
    foo: file(),
  });

  getValues().foo; //=> File | undefined

  return <input ref={field('foo')} type="file" />;
};

`files()`

Results in readonly File[].

import React from 'react';
import { files, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { field, getValues } = useForm({
    foo: files(),
  });

  getValues().foo; //=> readonly File[]

  return <input ref={field('foo')} type="file" multiple />;
};

Validation

Field spec

`required()`

import React from 'react';
import {
  checkbox,
  file,
  files,
  number,
  numberChoice,
  required,
  text,
  textChoice,
  useForm,
} from 'react-magical-form';

export const Form: React.FC = () => {
  useForm({
    f1: text({
      spec: required(), // should not be empty
    }),
    f2: textChoice({
      spec: required(), // should be selected
    }),
    f3: number({
      spec: required(), // should be empty and a number value
    }),
    f4: numberChoice({
      spec: required(), // should be selected
    }),
    f5: checkbox({
      spec: required(), // should be checked
    }),
    f6: file({
      spec: required(), // should be uploaded
    }),
    f7: files({
      spec: required(), // should be uploaded at least one
    }),
  });

  return null;
};

`minLength(limit: number)`

import React from 'react';
import { minLength, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  useForm({
    f1: text({
      spec: minLength(10), // should have length which is greater than or equal to 10
    }),
  });

  return null;
};

`maxLength(limit: number)`

import React from 'react';
import { maxLength, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  useForm({
    f1: text({
      spec: maxLength(32), // should have length which is smaller than or equal to 32
    }),
  });

  return null;
};

`pattern(regexp: RegExp)`

import React from 'react';
import { pattern, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  useForm({
    f1: text({
      spec: pattern(/-foo-/), // should match given pattern
    }),
  });

  return null;
};

`oneOfTexts(...values: readonly string[])`

import React from 'react';
import { oneOfTexts, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  useForm({
    f1: text({
      spec: oneOfTexts('foo', 'bar', 'baz'), // should be one of 'foo', 'bar', and 'baz'
    }),
  });

  return null;
};

`min(limit: number)`

import React from 'react';
import { min, number, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  useForm({
    f1: number({
      spec: min(1), // should be greater than or equal to 1
    }),
  });

  return null;
};

`max(limit: number)`

import React from 'react';
import { max, number, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  useForm({
    f1: number({
      spec: max(10), // should be smaller than or equal to 10
    }),
  });

  return null;
};

`range(min: number, max: number)`

import React from 'react';
import { number, range, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  useForm({
    f1: number({
      spec: range(0, 10), // should be between 0 and 10
    }),
  });

  return null;
};

`integer()`

import React from 'react';
import { integer, number, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  useForm({
    f1: number({
      spec: integer, // should be an integer
    }),
  });

  return null;
};

`oneOfNumbers(...values: readonly number[])`

import React from 'react';
import { oneOfNumbers, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  useForm({
    f1: text({
      spec: oneOfNumbers(1, 2, 3), // should be one of 1, 2, and 3
    }),
  });

  return null;
};

`exact<T extends number | string>(value: T)`

import React from 'react';
import { exact, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  useForm({
    f1: text({
      spec: exact('foo'), // should be 'foo'
    }),
  });

  return null;
};

`confirmationOf<T extends number | string>(value: T)`

Alias to exact(), but its default error message is different.
This is supporsed to used in useRules().

Form rules

If some fields have rules depend on other fields, use useRules().

import React from 'react';
import {
  confirmationOf,
  required,
  text,
  useForm,
  validationError,
} from 'react-magical-form';

export const Form: React.FC = () => {
  const { useRules } = useForm({
    password: text({
      spec: required(),
    }),
    passwordConfirmation: text({
      spec: required(),
    }),
  });

  // If you use `useRules()`, DO NOT USE any apis from `useForm()` except `useRules()`.
  // Instead, use apis from `useRules()`.
  const { errors, field, getValues, ...apis } = useRules({
    passwordConfirmation: (otherValues) => confirmationOf(otherValues.password),
  });

  return null;
};

Magical type refinement

If handleSubmit runs its callback, all validations should be passed, so some types of field values can be refined.
react-magical-form implements this behavior.

Refinement by `required()`

import React from 'react';
import {
  checkbox,
  file,
  files,
  number,
  numberChoice,
  required,
  textChoice,
  useForm,
} from 'react-magical-form';

export const Form: React.FC = () => {
  const { getValues, handleSubmit } = useForm({
    f1: textChoice({
      spec: required(),
    }),
    f2: number({
      spec: required(),
    }),
    f3: numberChoice({
      spec: required(),
    }),
    f4: checkbox({
      spec: required(),
    }),
    f5: file({
      spec: required(),
    }),
    f6: files({
      spec: required(),
    }),
  });

  getValues().f1; //=> string | undefined
  getValues().f2; //=> number | undefined
  getValues().f3; //=> number | undefined
  getValues().f4; //=> boolean
  getValues().f5; //=> File | undefined
  getValues().f6; //=> readonly File[]

  return (
    <form
      onSubmit={handleSubmit((values) => {
        values.f1; //=> string
        values.f2; //=> number
        values.f3; //=> number
        values.f4; //=> true
        values.f5; //=> File
        values.f6; //=> readonly [File, ...File[]]
      })}
    />
  );
};

Refinement by `oneOfTexts()`

import React from 'react';
import {
  number,
  numberChoice,
  oneOfTexts,
  text,
  textChoice,
  useForm,
} from 'react-magical-form';

export const Form: React.FC = () => {
  const { getValues, handleSubmit } = useForm({
    f1: textChoice({
      spec: oneOfTexts('foo', 'bar'),
    }),
  });

  getValues().f1; //=> string | undefined

  return (
    <form
      onSubmit={handleSubmit((values) => {
        values.f1; //=> "foo" | "bar" | undefined
      })}
    />
  );
};

Refinement by `oneOfNumbers()`

import React from 'react';
import {
  number,
  numberChoice,
  oneOfNumbers,
  text,
  textChoice,
  useForm,
} from 'react-magical-form';

export const Form: React.FC = () => {
  const { getValues, handleSubmit } = useForm({
    f1: number({
      spec: oneOfNumbers(1, 2),
    }),
    f2: numberChoice({
      spec: oneOfNumbers(1, 2),
    }),
  });

  getValues().f1; //=> number | undefined
  getValues().f2; //=> number | undefined

  return (
    <form
      onSubmit={handleSubmit((values) => {
        values.f1; //=> 1 | 2 | undefined
        values.f2; //=> 1 | 2 | undefined
      })}
    />
  );
};

Refinement composition

import React from 'react';
import {
  compose,
  number,
  numberChoice,
  oneOfNumbers,
  oneOfTexts,
  required,
  textChoice,
  useForm,
} from 'react-magical-form';

export const Form: React.FC = () => {
  const { getValues, handleSubmit } = useForm({
    f1: textChoice({
      spec: oneOfTexts('foo', 'bar'),
    }),
    f2: textChoice({
      spec: compose(
        required(),
        oneOfTexts('foo', 'bar'),
      ),
    }),
    f3: number({
      spec: oneOfNumbers(1, 2),
    }),
    f4: numberChoice({
      spec: compose(
        required(),
        oneOfNumbers(1, 2),
      ),
    }),
  });

  getValues().f1; //=> string | undefined
  getValues().f2; //=> string | undefined
  getValues().f3; //=> number | undefined
  getValues().f4; //=> number | undefined

  return (
    <form
      onSubmit={handleSubmit((values) => {
        values.f1; //=> "foo" | "bar" | undefined
        values.f2; //=> "foo" | "bar"
        values.f3; //=> 1 | 2 | undefined
        values.f4; //=> 1 | 2
      })}
    />
  );
};

Refinement by `useRules()`

import React from 'react';
import {
  compose,
  confirmationOf,
  oneOfTexts,
  required,
  text,
  textChoice,
  useForm,
} from 'react-magical-form';

export const Form: React.FC = () => {
  const { useRules } = useForm({
    field: textChoice({
      spec: compose(
        required(),
        oneOfTexts('foo', 'bar'),
      ),
    }),
    fieldConfirmation: text(),
  });

  const { getValues, handleSubmit } = useRules({
    fieldConfirmation: (otherFields) => confirmationOf(otherFields.field),
  });

  getValues().field; //=> string | string
  getValues().fieldConfirmation; //=> string

  return (
    <form
      onSubmit={handleSubmit((values) => {
        values.field; //=> "foo" | "bar"
        values.fieldConfirmation; //=> "foo" | "bar"
      })}
    />
  );
};

APIs

`field(fieldName: <NAME_OF_FIELD>)`

Bind HTML element to field instance.

import React from 'react';
import { text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { field } = useForm({
    f1: text(),
  });

  return <input ref={field('f1')} />;
};

`useRules(rules: <FORM_RULES>)`

Set form rules and return new form APIs.

const { useRules } = useForm({
  beginning: number({
    spec: required(),
  }),
  end: numberChoice({
    spec: required(),
  }),
});

const { errors, field, getValues, ...apis } = useRules({
  end: (otherValues) => min(otherValues.beginning),
});

return null;

`getValues()`

import React from 'react';
import { number, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { getValues } = useForm({
    f1: text(),
    f2: number(),
  });

  getValues(); //=> { "f1": string, "f2": number | undefined }

  return null;
};

`setValue(fieldName: <NAME_OF_FIELD>, value: <VALUE_TYPE_OF_FIELD>)`

import React from 'react';
import { number, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { setValue } = useForm({
    f1: number(),
  });

  setValue('f1', 0);
  setValue('f1', undefined);

  return null;
};

`setValues(values: <VALUES_TYPE>)`

import React from 'react';
import { number, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { setValues } = useForm({
    f1: text(),
    f2: number(),
  });

  setValues({
    f1: 'foo',
    f2: 1,
  });

  return null;
};

`errors`

Error messages of latest validation, as object with same keys of fields.

import React from 'react';
import { required, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { errors } = useForm({
    f1: text({
      spec: required(),
    }),
  });

  errors; //=> { "f1": readonly string[] }

  return null;
};

`validate()`

Runs validations manually.

import React, { useEffect } from 'react';
import { required, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { validate } = useForm({
    f1: text({
      spec: required(),
    }),
  });

  useEffect(() => {
    validate();
  }, []);

  return null;
};

`reset()`

Sets all field values to initial values and clears all errors.

import React, { useEffect } from 'react';
import { required, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { reset } = useForm({
    f1: text({
      spec: required(),
    }),
  });

  useEffect(() => {
    reset();
  }, []);

  return null;
};

`clear()`

Clears all field values and errors.

import React, { useEffect } from 'react';
import { required, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { clear } = useForm({
    f1: text({
      spec: required(),
    }),
  });

  useEffect(() => {
    clear();
  }, []);

  return null;
};

`clearErrors()`

Clears all errors.

import React, { useEffect } from 'react';
import { required, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { clearErrors } = useForm({
    f1: text({
      spec: required(),
    }),
  });

  useEffect(() => {
    clearErrors();
  }, []);

  return null;
};

`handleSubmit(f: (values: <VALUES_TYPE>) => void | Promise<void>)`

Handles form submittion running given callback.

import React, { useEffect } from 'react';
import { required, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { handleSubmit } = useForm({
    f1: text({
      spec: required(),
    }),
  });

  return <form onSubmit={handleSubmit(() => {})} />;
};

`isSubmitting`

import React from 'react';
import { required, text, useForm } from 'react-magical-form';

export const Form: React.FC = () => {
  const { isSubmitting } = useForm({
    f1: text({
      spec: required(),
    }),
  });

  isSubmitting; //=> boolean

  return null;
};

Customizing error messages

[WIP]

Using your own validators

[WIP]

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.circleci		.circleci
.vscode		.vscode
src		src
.eslintignore		.eslintignore
.eslintrc		.eslintrc
.gitignore		.gitignore
.huskyrc		.huskyrc
.lintstagedrc		.lintstagedrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
README.md		README.md
babel.config.js		babel.config.js
jest.config.js		jest.config.js
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.jest.json		tsconfig.jest.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

mozisan/react-magical-form

Folders and files

Latest commit

History

Repository files navigation

react-magical-form

Attention

Table of contents

Installation

Basic Usage

Supported field types

text()

number()

checkbox()

textChoice()

numberChoice()

file()

files()

Validation

Field spec

required()

minLength(limit: number)

maxLength(limit: number)

pattern(regexp: RegExp)

oneOfTexts(...values: readonly string[])

min(limit: number)

max(limit: number)

range(min: number, max: number)

integer()

oneOfNumbers(...values: readonly number[])

exact<T extends number | string>(value: T)

confirmationOf<T extends number | string>(value: T)

Form rules

Magical type refinement

Refinement by required()

Refinement by oneOfTexts()

Refinement by oneOfNumbers()

Refinement composition

Refinement by useRules()

APIs

field(fieldName: <NAME_OF_FIELD>)

useRules(rules: <FORM_RULES>)

getValues()

setValue(fieldName: <NAME_OF_FIELD>, value: <VALUE_TYPE_OF_FIELD>)

setValues(values: <VALUES_TYPE>)

errors

validate()

reset()

clear()

clearErrors()

handleSubmit(f: (values: <VALUES_TYPE>) => void | Promise<void>)

isSubmitting