<input>

The built-in browser <input> component lets you render different kinds of form inputs.

<input />

Reference

<input>

To display an input, render the built-in browser <input> component.

<input name="myInput" />

See more examples below.

Props

<input> supports all common element props.

  • formAction: A string or function. Overrides the parent <form action> for type="submit" and type="image". When a URL is passed to action the form will behave like a standard HTML form. When a function is passed to formAction the function will handle the form submission. See <form action>.

You can make an input controlled by passing one of these props:

  • checked: A boolean. For a checkbox input or a radio button, controls whether it is selected.
  • value: A string. For a text input, controls its text. (For a radio button, specifies its form data.)

When you pass either of them, you must also pass an onChange handler that updates the passed value.

These <input> props are only relevant for uncontrolled inputs:

These <input> props are relevant both for uncontrolled and controlled inputs:

  • accept: A string. Specifies which filetypes are accepted by a type="file" input.
  • alt: A string. Specifies the alternative image text for a type="image" input.
  • capture: A string. Specifies the media (microphone, video, or camera) captured by a type="file" input.
  • autoComplete: A string. Specifies one of the possible autocomplete behaviors.
  • autoFocus: A boolean. If true, React will focus the element on mount.
  • dirname: A string. Specifies the form field name for the element's directionality.
  • disabled: A boolean. If true, the input will not be interactive and will appear dimmed.
  • children: <input> does not accept children.
  • form: A string. Specifies the id of the <form> this input belongs to. If omitted, it's the closest parent form.
  • formAction: A string. Overrides the parent <form action> for type="submit" and type="image".
  • formEnctype: A string. Overrides the parent <form enctype> for type="submit" and type="image".
  • formMethod: A string. Overrides the parent <form method> for type="submit" and type="image".
  • formNoValidate: A string. Overrides the parent <form noValidate> for type="submit" and type="image".
  • formTarget: A string. Overrides the parent <form target> for type="submit" and type="image".
  • height: A string. Specifies the image height for type="image".
  • list: A string. Specifies the id of the <datalist> with the autocomplete options.
  • max: A number. Specifies the maximum value of numerical and datetime inputs.
  • maxLength: A number. Specifies the maximum length of text and other inputs.
  • min: A number. Specifies the minimum value of numerical and datetime inputs.
  • minLength: A number. Specifies the minimum length of text and other inputs.
  • multiple: A boolean. Specifies whether multiple values are allowed for <type="file" and type="email".
  • name: A string. Specifies the name for this input that's submitted with the form.
  • onChange: An Event handler function. Required for controlled inputs. Fires immediately when the input's value is changed by the user (for example, it fires on every keystroke). Behaves like the browser input event.
  • onChangeCapture: A version of onChange that fires in the capture phase.
  • onInput: An Event handler function. Fires immediately when the value is changed by the user. For historical reasons, in React it is idiomatic to use onChange instead which works similarly.
  • onInputCapture: A version of onInput that fires in the capture phase.
  • onInvalid: An Event handler function. Fires if an input fails validation on form submit. Unlike the built-in invalid event, the React onInvalid event bubbles.
  • onInvalidCapture: A version of onInvalid that fires in the capture phase.
  • onSelect: An Event handler function. Fires after the selection inside the <input> changes. React extends the onSelect event to also fire for empty selection and on edits (which may affect the selection).
  • onSelectCapture: A version of onSelect that fires in the capture phase.
  • pattern: A string. Specifies the pattern that the value must match.
  • placeholder: A string. Displayed in a dimmed color when the input value is empty.
  • readOnly: A boolean. If true, the input is not editable by the user.
  • required: A boolean. If true, the value must be provided for the form to submit.
  • size: A number. Similar to setting width, but the unit depends on the control.
  • src: A string. Specifies the image source for a type="image" input.
  • step: A positive number or an 'any' string. Specifies the distance between valid values.
  • type: A string. One of the input types.
  • width: A string. Specifies the image width for a type="image" input.

Caveats

  • Checkboxes need checked (or defaultChecked), not value (or defaultValue).
  • If a text input receives a string value prop, it will be treated as controlled.
  • If a checkbox or a radio button receives a boolean checked prop, it will be treated as controlled.
  • An input can't be both controlled and uncontrolled at the same time.
  • An input cannot switch between being controlled or uncontrolled over its lifetime.
  • Every controlled input needs an onChange event handler that synchronously updates its backing value.

Usage

Displaying inputs of different types

To display an input, render an <input> component. By default, it will be a text input. You can pass type="checkbox" for a checkbox, type="radio" for a radio button, or one of the other input types.

export default function MyForm() {
  return (
    <>
      <label>
        Text input: <input name="myInput" />
      </label>
      <hr />
      <label>
        Checkbox: <input type="checkbox" name="myCheckbox" />
      </label>
      <hr />
      <p>
        Radio buttons:
        <label>
          <input type="radio" name="myRadio" value="option1" />
          Option 1
        </label>
        <label>
          <input type="radio" name="myRadio" value="option2" />
          Option 2
        </label>
        <label>
          <input type="radio" name="myRadio" value="option3" />
          Option 3
        </label>
      </p>
    </>
  );
}
label { display: block; }
input { margin: 5px; }

Providing a label for an input

Typically, you will place every <input> inside a <label> tag. This tells the browser that this label is associated with that input. When the user clicks the label, the browser will automatically focus the input. It's also essential for accessibility: a screen reader will announce the label caption when the user focuses the associated input.

If you can't nest <input> into a <label>, associate them by passing the same ID to <input id> and <label htmlFor>. To avoid conflicts between multiple instances of one component, generate such an ID with useId.

import { useId } from 'react';

export default function Form() {
  const ageInputId = useId();
  return (
    <>
      <label>
        Your first name:
        <input name="firstName" />
      </label>
      <hr />
      <label htmlFor={ageInputId}>Your age:</label>
      <input id={ageInputId} name="age" type="number" />
    </>
  );
}
input { margin: 5px; }

Providing an initial value for an input

You can optionally specify the initial value for any input. Pass it as the defaultValue string for text inputs. Checkboxes and radio buttons should specify the initial value with the defaultChecked boolean instead.

export default function MyForm() {
  return (
    <>
      <label>
        Text input: <input name="myInput" defaultValue="Some initial value" />
      </label>
      <hr />
      <label>
        Checkbox: <input type="checkbox" name="myCheckbox" defaultChecked={true} />
      </label>
      <hr />
      <p>
        Radio buttons:
        <label>
          <input type="radio" name="myRadio" value="option1" />
          Option 1
        </label>
        <label>
          <input
            type="radio"
            name="myRadio"
            value="option2"
            defaultChecked={true}
          />
          Option 2
        </label>
        <label>
          <input type="radio" name="myRadio" value="option3" />
          Option 3
        </label>
      </p>
    </>
  );
}