Optimal Formik

A formik alternative that optimizes for performance.

Installation

npm install optimal-formik

Usage

import {
  OptimalFormik,
  Input,
  IterableField,
  IterableRenderer,
  ZodValidator,
} from "optimal-formik";
import { z } from "zod";

const validationSchema = z.object({
  name: z.string().min(3),
  age: z.number().min(18),
  friends: z.array(
    z.object({
      name: z.string().min(3),
      age: z.number().min(18).optional(),
    })
  ),
});

const formValidator = new ZodValidator(validationSchema);

type Data = z.infer<typeof validationSchema>;

const initialValues: Data = {
  name: "John",
  age: 30,
  friends: [
    {
      name: "Jane",
    },
    {
      name: "Bob",
    },
  ],
};

function App() {
  return (
    <>
      <OptimalFormik<Data>
        formID={"test"}
        initialValues={initialValues}
        zodValidationSchema={formValidator}
        onSubmit={(data) => {
          console.log(data);
        }}
      >
        <Input name="name" label="Name" />
        <Input type="number" name="age" label="Age" />
        <IterableField<Data["friends"]> name="friends" label="Friends">
          {({ push, remove, modify, setValue }) => (
            <>
              <IterableRenderer<Data["friends"]>>
                {(path, key) => (
                  <>
                    <Input name={path.concat("name")} label="Name" />
                    <Input
                      type="number"
                      name={path.concat("age")}
                      label="Age"
                    />
                    <button onClick={() => remove(path)}>Remove</button>
                  </>
                )}
              </IterableRenderer>
              <button
                onClick={() =>
                  push({
                    name: "",
                    age: undefined,
                  })
                }
              >
                Add Friend
              </button>
              <button onClick={() => setValue(initialValues.friends)}>
                Reset
              </button>
            </>
          )}
        </IterableField>
      </OptimalFormik>
    </>
  );
}

export default App;

Components and helpers

<OptimalFormik> (form root)

Props

| Prop | Type | Description | | -------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------- | | formID (required) | string | Unique ID of the form. | | initialValues (required) | Record<string, any> | Initial values of the form. | | onSubmit (required) | (data: Record<string, any>) => void | function that is executed when the submit button is pressed | | validator | Validator | Can be ZodValidator, YupValidator or a custom child of Validator | | preventSubmitOnEnter | boolean | Prevent submit on Enter pressed | | className | string | ... |

Primary components (with Label and ErrorMessage)

Every element with Label has these props available:

| Prop | Type | Description | | ------------------ | ----------------------------- | ------------------------------- | | name (required) | string \| Path | Path to the field | | label (required) | string \| React.JSX.Element | Label of the field | | hideLabel | boolean | Hides the fields label | | containerClass | string | Class name of input's container | | labelClass | string | Class name of input's label | | errorClass | string | Class name of ErrorMessage |

<Input>

Props

| Prop | Type | Description | | ------------- | ---------------- | ----------------------------------------------------------------------------------- | | Common props | ... | See in the start of this section | | Element props | HTMLInputProps | ... |

<Select>

Props

| Prop | Type | Description | | ------------- | ----------------- | ----------------------------------------------------------------------------------- | | Common props | ... | See in the start of this section | | Element props | HTMLSelectProps | ... |

<TextArea>

Props

| Prop | Type | Description | | ------------- | ------------------- | ----------------------------------------------------------------------------------- | | Common props | ... | See in the start of this section | | Element props | HTMLTextAreaProps | ... |

<CheckboxInput>

Props

hideLabel is not available here

| Prop | Type | Description | | ------------- | ------------------ | ----------------------------------------------------------------------------------- | | Common props | ... | See in the start of this section | | Element props | HTMLInputElement | ... |

<IterableField>

Props

| Prop | Type | Description | | --------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------ | | Common props | ... | See in the start of this section | | children (required) | (...helpers: ...) => React.JSX.Element | The children is a function providing useful functions helpers to manipulate array and objects. | | Element props | HTMLDivProps | ... |

Children Helpers

Where E is an element of A, A is the iterable itself, and Path is a class for strict path management.

Updater<A> is a callback like this (value: A) => void. This provides flexibility, but if you need to overwrite the hole object you need to use setValue.

  /** Push new item to array */
  push(value: E): void;
  /** Insert new item to object */
  insert(key: string, value: E): void;
  /** Remove item from array or object */
  remove(path: Path<A>): void;
  /** Modify object or array */
  modify(updater: Updater<A>): void;
  /** Set value of object or array */
  setValue(value: A): void;

Primary components

<IterableRenderer>

This component don't have Label and ErrorMessage but alway is a child of IterableField. This component works like Array.map.

Props

| Prop | Type | Description | | --------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | as (default: div) | keyof React.JSX.IntrinsicElements | Tag name of this component | | className | string | Class of this component | | children (required) | (path: Path<E>, key: string \| number) => React.JSX.Element | The children is a function providing the path of the array or object and the key. The key can be the index of the array or key of the object. |

<SubmitButton>

Use this component to fire onSubmit form callback.

Props: HTMLButtonElementProps

Complementary components

Useful to make your own OptimalFormik components

<Label>

Label with ErrorMessage

Props

| Prop | Type | Description | | --------------------- | ----------------------------- | ---------------------- | | name (required) | string \| Path | Path to the field | | children (required) | string \| React.JSX.Element | Label of the field | | hideLabel | boolean | Hides the fields label | | ... | HTMLLabelProps | ... |

<ErrorMessage>

Show an error if exist

Props

| Prop | Type | Description | | ----------------- | ---------------- | ----------------- | | name (required) | string \| Path | Path to the field | | Element props | HTMLDivProps | ... |

<RedDot>

Returns null if no errors were detected embed in the field, else returns the div element. Useful to show if there are errors in hidden sub-fields.

Props

| Prop | Type | Description | | ----------------- | ---------------- | ----------------- | | name (required) | string \| Path | Path to the field | | Element props | HTMLDivProps | ... |

Helpers

Path

class Path {
  constructor(key: string | number, path = "") {}

  concat(key: string | number): Path;

  toString(): string;
}

Validator (abstract class)

Useful if you don't use yup or zod as validation schema.

Obs: In both cases value will be the form current data

type ValidationResult =
  | {
      success: true;
    }
  | {
      success: false;
      errors: {
        path?: (string | number)[];
        message: string;
      }[];
    };

abstract class Validator {
  constructor(protected schema: any) {}

  abstract validate(value: unknown): Promise<ValidationResult>;

  abstract validateAt(path: string, value: unknown): ValidationResult;
}

Use

class CustomValidator extends Validator {
  constructor(protected schema) {
    // ...
  }

  async validate(value: unknown) {
    // return the validation result
  }

  async validateAt(path: string, value: unknown) {
    // return the validation result
  }
}

React Context

• If you want to get FormID without useFormID or useForm, you can use OptimalFormikContext.
• If you want to get the current path generated by IterableField you can use PathContext.

Hooks

useFormID

Retrieves the current form ID from the OptimalFormikContext. This ID is defined in the parent OptimalFormik and is used to identify the form.

useForm

type FormConfig<T extends AnyObject> = {
  formID: string;
  initialValues: T;
  onSubmit(values: T): void;
  validator?: Validator;
  preventSubmitOnEnter?: boolean;
};

type FormBasicData<T> = {
  data: T;
  touched: Record<string, boolean | undefined>;
  errors: Record<string, string | undefined>;
  isValidating?: boolean;
  isSubmitting?: boolean;
};

type Form<T extends AnyObject> = FormBasicData<T> & {
  config: FormConfig<T>;
  updateForm(updater: Updater<FormBasicData<T>>): void;
};

Example

type MyForm = {
  title: string
  description: string
  counters: {
    counter1: number
    counter2: number
  }
}

const updateForm = useForm((s: Form<MyForm>) => s.updateForm)
const { data, error, touched } = useForm((s: Form<MyForm>) => ({
  data: s.data.counter1
  error: s.errors['counters.counter1']
  touched: s.touched['counters.counter1']
}))

useField

Like useField from Formik.

// you can import this
enum FieldDataType {
  STRING = "string",
  NUMBER = "number",
  BOOLEAN = "boolean",
}

type InputProps<T> = {
  value: T | undefined;
  checked: T | undefined;
  onChange: ChangeEventHandler<
    HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
  >;
  onBlur: FocusEventHandler;
};

type Meta<T> = {
  data: T;
  error: string | undefined;
  touched: boolean | undefined;
  initialValue: T | null;
};

type Helpers<T> = {
  setValue: (value: T) => void;
  setError: (error: string | undefined) => void;
  setTouched: (touched: boolean) => void;
  validate: () => void;
};

// T is the type of the data and F the type of the form
type useField<T, F> = (
  path: Path<F> | string,
  type?: FieldDataType
) => [InputProps<T>, Meta<T>, Helpers<T>];

useFieldErrorData

type useFieldErrorData = (path: Path<AnyObject> | string) => {
  error?: string;
  touched?: boolean;
};

useEmbedErrorsCheck

Returns true if some error is inside the selected path.

type useEmbedErrorsCheck = (path: Path<AnyObject> | string) => boolean;