Form #

A set of components and models that process form data.

Import #

• Basic:
  • Form: Used to define forms that support data validation.
  • Form.Label: Title corresponding to the form field.
  • Form.Control: Defines the control for the form field. Defaults to the Input component. Can customize the component through the accepter property.
• Layout:
  • Form.Stack: Used to layout a group of form controls.
  • Form.Group: Used to layout a single form control.
• Field State:
  • Form.Text: Provides help information for form fields.
  • Form.ErrorMessage: Displays error message for form fields.
• Hooks
  • useFormControl: A hook that provides form control functionality for custom form components, enabling seamless integration with the Form component.

Layouts #

Vertical Layout #

Fluid #

The fluid property allows the Input 100% of the form to fill the container, valid only in vertical layouts.

Horizontal Layout #

Inline Layout #

Layout In Modal #

Status #

Help Text #

<Form.Text> A help description can be defined below the form component. If the tooltip property is set, an icon will be displayed on the form component and the help description information will be displayed as <Tooltip>.

Error Message #

Error message can be set in 2 ways:

• The <Form.Control> component passes an errorMessage property setting error message, and errorPlacement sets the location of the error message display.
• Customize a prompt message.

Disabled and read only #

Accessibility #

ARIA properties #

• You should set the aria-label or aria-labelledby property for each form so that the screen reader can read the purpose of the form correctly.

• Through the controlId prop of <Form.Group>, you can set id on <Form.Control> and set htmlFor on <Form.Label>. In addition, aria-labelledby and aria-describeby will be generated for <Form.Control>, corresponding to the id of <Form.Label> and <Form.Text>.

<Form.Group controlId="name">
  <Form.Label>Username</Form.Label>
  <Form.Control />
  <Form.Text>Username is required</Form.Text>
</Form.Group>

HTML:

<div class="rs-form-group" role="group">
  <label id="name-control-label" for="name" class="rs-form-control-label">Username</label>
  <div class="rs-form-control rs-form-control-wrapper">
    <input
      id="name"
      class="rs-input"
      aria-labelledby="name-control-label"
      aria-describedby="name-help-text"
    />
  </div>
  <span id="name-help-text" class="rs-form-help-text">Username is required</span>
</div>

Required JavaScript features #

• Click the button of type='submit' in the Form, and the submit event of the form will be triggered automatically.

Props #

<Form> #

<Form.Stack> #

<Form.Control> #

<Form.Group> #

<Form.Label> #

<Form.Text> #

<Form.ErrorMessage> #

Form Ref #

Schema #

Schema depends on the schema-typed library for defining data models.

Placement #

/**
 * Placement options for error messages in form controls.
 * The `static` option is supported from v6.0.0 onwards.
 */
type ErrorMessagePlacement =
  | 'static'
  | 'bottomStart'
  | 'bottomEnd'
  | 'topStart'
  | 'topEnd'
  | 'leftStart'
  | 'leftEnd'
  | 'rightStart'
  | 'rightEnd';

Hooks #

useFormControl #

The useFormControl hook provides form control functionality for custom form components. It must be used within a <Form> component.

const {
  value, // Current field value
  error, // Field error message
  plaintext, // Whether the field is in plaintext mode
  readOnly, // Whether the field is read-only
  disabled, // Whether the field is disabled
  onChange, // Handler for field value changes
  onBlur, // Handler for field blur events
  onCheck, // Handler for manually triggering field validation
  setValue // Directly sets the field value
} = useFormControl(props);

Return Values #

Example #

import { useFormControl } from 'rsuite';

function CustomField({ name, label }) {
  const { value, error, onChange, onBlur } = useFormControl({ name });

  return (
    <div className="custom-field">
      <label>{label}</label>
      <input value={value || ''} onChange={e => onChange(e.target.value, e)} onBlur={onBlur} />
      {error && <div className="error-message">{error}</div>}
    </div>
  );
}

// Usage
<Form>
  <CustomField name="email" label="Email" />
</Form>;