Form

A wrapper component that handles the submission of forms.

Use onSubmit as a callback for when your form is submitted.

import {Form, FormLayout, Checkbox, TextField, Button} from '@shopify/polaris';
import {useState, useCallback} from 'react';

function FormOnSubmitExample() {
  const [newsletter, setNewsletter] = useState(false);
  const [email, setEmail] = useState('');

  const handleSubmit = useCallback((_event) => {
    setEmail('');
    setNewsletter(false);
  }, []);

  const handleNewsLetterChange = useCallback(
    (value) => setNewsletter(value),
    [],
  );

  const handleEmailChange = useCallback((value) => setEmail(value), []);

  return (
    <Form onSubmit={handleSubmit}>
      <FormLayout>
        <Checkbox
          label="Sign up for the Polaris newsletter"
          checked={newsletter}
          onChange={handleNewsLetterChange}
        />

        <TextField
          value={email}
          onChange={handleEmailChange}
          label="Email"
          type="email"
          autoComplete="email"
          helpText={
            <span>
              We’ll use this email address to inform you on future changes to
              Polaris.
            </span>
          }
        />

        <Button submit>Submit</Button>
      </FormLayout>
    </Form>
  );
}

Use in forms to toggle native form validation.

import {Form, FormLayout, TextField, Button} from '@shopify/polaris';
import {useState, useCallback} from 'react';

function FormWithoutNativeValidationExample() {
  const [url, setUrl] = useState('');

  const handleSubmit = useCallback((_event) => setUrl(''), []);

  const handleUrlChange = useCallback((value) => setUrl(value), []);

  return (
    <Form noValidate onSubmit={handleSubmit}>
      <FormLayout>
        <TextField
          value={url}
          onChange={handleUrlChange}
          label="App URL"
          type="url"
          autoComplete="off"
        />

        <Button submit>Submit</Button>
      </FormLayout>
    </Form>
  );
}

Props

Want to help make this feature better? Please share your feedback.

interface FormProps
acceptCharset?string

Space separated list of character encodings.

action?string

Where to send form-data on submittal.

autoComplete?boolean

Grants the browser the ability to autocomplete input elements.

children?React.ReactNode

The content to display inside the form.

encType?'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'

Media type when submitting content to server.

implicitSubmit?boolean

Toggles if form submits on Enter keypress. Defaults to true.

method?'post' | 'get' | 'action'

Method used to submit form.

name?string

A unique name for the form.

noValidate?boolean

Whether or not form is validated when submitting.

preventDefault?boolean

Blocks the default form action.

target?string

Where to display response after form submittal.

onSubmit(event: React.FormEvent<HTMLFormElement>) => void

Callback when form is submitted.

Best practices

The form component should be used to:

  • Wrap around all form input elements
  • Emulate the native HTML form element behavior with a custom onSubmit callback


Accessibility

The form component wraps content in an HTML <form> element. This helps to support assistive technologies that use different interaction and browse modes.

Forms can have only one submit button and it must be at the end of the form. By default, buttons added to the form are given a type attribute set to button to avoid conflicts. To make a button the submit button instead (type="submit"), set the submit prop on the button.

Keyboard support

By default, the implicitSubmit prop is set to true. This allows merchants to submit the form with the enter/return key when focus is in any text field inside the form. This provides a shortcut for keyboard users. If this behavior doesn’t fit the form, then set the prop to false.