Forms

NextUI form components are designed to be flexible and function as HTML form elements. They support form data submission, custom validation, real-time validation, and offer an accessible UI.

Labels and help text

Accessible forms require clear and descriptive labels. NextUI components allow you to add labels to each field through the label prop. You can also display help text such as descriptions or error messages.

import {Input} from "@nextui-org/react";

<Input
  type="password"
  label="Password"
  description="Password must be at least 8 characters."
/>

Labels should usually be visually displayed, but in rare cases, you need to provide an aria-label or aria-labelledby attribute to identify the element for screen readers.

Submitting data

How you submit form data depends on your framework, application, and server. By default, HTML forms are submitted via a full-page refresh in the browser. You can call preventDefault in the onSubmit event to handle form data submission via an API.

Uncontrolled forms

A simple way to get form data is to use FormData API. You can send this data to a backend API or convert it into a JavaScript object using Object.fromEntries. Each field should have a name prop to identify it, and the values will be serialized as strings by the browser.

import {Button, Form, Input} from "@nextui-org/react";

function Example() {
  const [submitted, setSubmitted] = React.useState(null);

  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    // Prevent default browser page refresh.
    e.preventDefault();

    // Get form data as an object.
    const data = Object.fromEntries(new FormData(e.currentTarget));

    // Submit data to your backend API. (currently logged to the console)
    console.log("Form submitted:", data);
  };

  return (
    <Form onSubmit={onSubmit}>
      <Input label="Name" name="name" />
      <Button type="submit">Submit</Button>
    </Form>
  );
}

Controlled forms

NextUI form components are uncontrolled by default, but if you need to manage state in real-time, you can use the useState hook to make the component controlled.

import {Button, Form, Input} from "@nextui-org/react";

function Example() {
  const [name, setName] = React.useState("");
  const onSubmit = (e) => {
    e.preventDefault();

    // Submit data to your backend API.
    alert(name);
  };

  return (
    <Form onSubmit={onSubmit}>
      <Input value={name} onValueChange={setName} />
      <Button type="submit">Submit</Button>
    </Form>
  );
}

Validation

Form validation is crucial for ensuring that users enter the correct data. NextUI supports native HTML constraint validation and allows for custom validation and real-time validation.

Built-in validation

NextUI form components support native HTML validation attributes like isRequired and minLength. These constraints are checked by the browser when the user commits changes (e.g., onBlur) or submits the form. You can display validation errors with custom styles instead of the browser's default UI.

import {Button, Form, Input} from "@nextui-org/react";

<Form validationBehavior="native">
  <Input name="email" type="email" isRequired />
  <Button type="submit">Submit</Button>
</Form>

To enable native validation, set validationBehavior="native". By default, validationBehavior="aria" is set, which only marks the field as required or invalid for assistive technologies, without preventing form submission. You can change the form defaults for your entire app using NextUI Provider.

Customizing error messages

By default, error messages are provided by the browser. You can customize these messages by providing a function to the errorMessage prop.

import {Button, Form, Input} from "@nextui-org/react";

<Form validationBehavior="native">
  <Input
    label="Number"
    isRequired
    min={0}
    max={100}
    errorMessage={(validationResult) => {
      if (validationResult.validationDetails.rangeOverflow) {
        return "Value is too high";
      }
      if (validationResult.validationDetails.rangeUnderflow) {
        return "Value is too low";
      }
      if (validationResult.validationDetails.valueMissing) {
        return "Value is required";
      }
    }}
  />
  <Button type="submit">Submit</Button>
</Form>

Note: The default error messages are localized by the browser based on the browser/operating system language settings. The locale setting in NextUI Provider does not affect validation errors.

Custom validation

In addition to built-in constraints, you can provide a function to the validate prop to support custom validation.

import {Button, Form, Input} from "@nextui-org/react";

<Form>
  <Input
    label="Number"
    type="number"
    validate={(value) => {
      if (value < 0 || value > 100) {
        return "Value must be between 0 and 100";
      }
    }}
  />
  <Button type="submit">Submit</Button>
</Form>

Realtime validation

If you want to display validation errors while the user is typing, you can control the field value and use the isInvalid prop along with the errorMessage prop.

import {Input} from "@nextui-org/react";

export function Example() {
  const [password, setPassword] = React.useState("");
  const errors: string[] = [];

  if (password.length < 8) {
    errors.push("Password must be 8 characters or more.");
  }
  if ((password.match(/[A-Z]/g) ?? []).length < 2) {
    errors.push("Password must include at least 2 upper case letters");
  }
  if ((password.match(/[^a-z]/gi) ?? []).length < 2) {
    errors.push("Password must include at least 2 symbols.");
  }

  return (
    <Input
      label="Name"
      value={password}
      onValueChange={setPassword}
      isInvalid={errors.length > 0}
      errorMessage={() => (
        <ul>
          {errors.map((error, i) => (
            <li key={i}>{error}</li>
          ))}
        </ul>
      )}
    />
  );
}

Server validation

Client-side validation provides immediate feedback, but you should also validate data on the server to ensure accuracy and security. NextUI allows you to display server-side validation errors by using the validationErrors prop in the Form component. This prop should be an object where each key is the field name and the value is the error message.

import {Button, Form, Input} from "@nextui-org/react";

function Example() {
  const [errors, setErrors] = React.useState({});
  const onSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();

    const data = Object.fromEntries(new FormData(e.currentTarget));
    const result = await callServer(data);

    setErrors(result.errors);
  };

  return (
    <Form validationErrors={errors} onSubmit={onSubmit}>
      <Input label="Username" name="username" />
      <Input label="Password" name="password" type="password" />
      <Button type="submit">Submit</Button>
    </Form>
  );
}

// Fake server used in this example.
function callServer(data) {
  return {
    errors: {
      username: "Sorry, this username is taken.",
    },
  };
}

Schema validation

NextUI supports errors from schema validation libraries like Zod. You can use Zod's flatten method to get error messages for each field and return them as part of the server response.

// In your server.
import {z} from "zod";

const schema = z.object({
  name: z.string().min(1),
  age: z.coerce.number().positive()
});

function handleRequest(formData: FormData) {
  const result = schema.safeParse(
    Object.fromEntries(formData)
  );
  if (!result.success) {
    return {
      errors: result.error.flatten().fieldErrors
    };
  }

  return {
    errors: {}
  };
}

React Server Actions

Server Actions that allows seamless form submission to the server and retrieval of results. The useActionState hook can be used to get the result of server actions (such as errors) after submitting a form.

// app/add-form.tsx
"use client";

import {useActionState} from "react";
import {Button, Input, Label} from "@nextui-org/react";
import {createTodo} from "@/app/actions";

export function AddForm() {
  const [{ errors }, formAction] = useActionState(createTodo, {
    errors: {}
  });

  return (
    <Form action={formAction} validationErrors={errors}>
      <Input name="todo" label="Task" />
      <Button type="submit">Add</Button>
    </Form>
  );
}

// app/actions.ts
"use server";

export async function createTodo(
  prevState: any,
  formData: FormData
) {
  try {
    // Create the todo.
  } catch (err) {
    return {
      errors: {
        todo: "Invalid todo."
      }
    };
  }
}

Remix

Remix actions handle form submissions on the server. You can use the useSubmit hook to submit form data to the server and the useActionData hook to retrieve validation errors from the server.

// app/routes/signup.tsx
import type {ActionFunctionArgs} from "@remix-run/node";
import {useActionData, useSubmit} from "@remix-run/react";
import {Button, Form, Input} from "@nextui-org/react";

export default function SignupForm() {
  const [errors, setErrors] = React.useState({});
  const onSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();

    const data = Object.fromEntries(new FormData(e.currentTarget));
    const result = await callServer(data);

    setErrors(result.errors);
  };

  return (
    <Form validationErrors={errors} onSubmit={onSubmit}>
      <Input label="Username" name="username" />
      <Input label="Password" name="password" type="password" />
      <Button type="submit">Submit</Button>
    </Form>
  );
}

export async function action(
  { request }: ActionFunctionArgs
) {
  try {
    // Validate data and perform action...
  } catch (err) {
    return {
      errors: {
        username: "Sorry, this username is taken."
      }
    };
  }
}

Form libraries

In most cases, the built-in validation features of NextUI are sufficient. However, if you're building more complex forms or integrating NextUI components into an existing form, you can use a form library like React Hook Form or Formik.

React Hook Form

You can integrate NextUI components using Controller. Controller allows you to manage field values and validation errors, and reflect the validation result in NextUI components.

import {Controller, useForm} from "react-hook-form";
import {Button, Input, Label} from "@nextui-org/react";

function App() {
  const { handleSubmit, control } = useForm({
    defaultValues: {
      name: ""
    }
  });
  const onSubmit = (data) => {
    // Call your API here.
  };

  return (
    <Form onSubmit={handleSubmit(onSubmit)}>
      <Controller
        control={control}
        name="name"
        render={({field: {name, value, onChange, onBlur, ref}, fieldState: {invalid, error}}) => (
          <Input
            ref={ref}
            isRequired
            errorMessage={error?.message}
            isInvalid={invalid}
            label="Name"
            name={name}
            value={value}
            onBlur={onBlur}
            onChange={onChange}
          />
        )}
        rules={{required: "Name is required."}}
      />
      <Button type="submit">Submit</Button>
    </Form>
  );
}