feat(Form): add useFormControl hook #4268

simonguo · May 6, 2025

https://rsuite-nextjs-git-feat-add-useformcontrol-hook-rsuite.vercel.app/components/form/

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);

Property	Type`(default)`	Description
checkAsync	boolean`(false)`	Whether to perform asynchronous validation
checkTrigger	'change' \| 'blur' \| null	The data validation trigger type, overrides the Form's checkTrigger
errorMessage	React.ReactNode	Custom error message to display
name	string	The name of the form field (required)
rule	CheckType	Validation rule (from Schema)
shouldResetWithUnmount	boolean`(false)`	Whether to remove field value and error when component unmounts
value	any	The current value

Return Values

Property	Type	Description
disabled	boolean	Whether the field is disabled (inherited from Form)
error	React.ReactNode	Field error message
onBlur	() => void	Handler for field blur events
onChange	(value: any, event: SyntheticEvent) => void	Handler for field value changes
onCheck	(value: any) => void	Handler for manually triggering field validation
plaintext	boolean	Whether the field is in plaintext mode (inherited from Form)
readOnly	boolean	Whether the field is read-only (inherited from Form)
setValue	(value: any, shouldValidate?: boolean) => void	Directly sets the field value without triggering onChange events. If shouldValidate is true, will trigger validation based on checkTrigger
value	any	Current field value

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>;

codesandbox · May 6, 2025

Review or Edit in CodeSandbox

Open the branch in Web Editor • VS Code • Insiders

Open Preview

Copilot

Pull Request Overview

This pull request introduces the new useFormControl hook, which streamlines form control functionality for custom form components and integrates them seamlessly within a Form component. Key changes include the implementation of the useFormControl hook, updates to import paths and helper functions in related files, and corresponding documentation updates across component and validation pages.

Reviewed Changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/useFormControl/useFormControl.tsx	New hook implementation and lifecycle handling for form control.
src/useFormControl/test/utilsSpec.ts	Updated import path for utils.
src/useFormControl/index.tsx	Export updates for the hook.
src/useFormControl/hooks/useField.ts	Updated import path for nameToPath.
src/index.tsx	Export inclusion of useFormControl.
src/FormControl/FormControl.tsx	Refactored to use the new hook; props and context values merged.
src/Form/hooks/useFormValidate.ts	Updated import path for nameToPath in validation hook.
src/Form/FormContext.tsx	Changed onFieldChange signature to allow an optional event.
Documentation files	Updated examples and descriptions for useFormControl functionality.

Files not reviewed (1)

docs/component.config.json: Language not supported

Comments suppressed due to low confidence (1)

src/Form/FormContext.tsx:14

[nitpick] Making the event parameter optional might affect consumers expecting the event argument. Ensure that all usages of onFieldChange suitably handle an undefined event.

onFieldChange: (name: string, value: any, event?: React.SyntheticEvent) => void;

src/useFormControl/useFormControl.tsx

docs/pages/components/popover/en-US/index.md

vercel · May 6, 2025

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
rsuite-nextjs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 7, 2025 4:05am
rsuite-storybook	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 7, 2025 4:05am

codesandbox-ci · May 6, 2025

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

codecov · May 6, 2025

Codecov Report

Attention: Patch coverage is 94.00000% with 3 lines in your changes missing coverage. Please review.

Project coverage is 89.94%. Comparing base (15dcdf3) to head (e03df5f).
Report is 9 commits behind head on next.

Files with missing lines	Patch %	Lines
src/useFormControl/useFormControl.tsx	91.89%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             next    #4268   +/-   ##
=======================================
  Coverage   89.94%   89.94%           
=======================================
  Files         565      566    +1     
  Lines       13183    13200   +17     
  Branches     3273     3276    +3     
=======================================
+ Hits        11857    11873   +16     
- Misses        621      622    +1     
  Partials      705      705

Flag	Coverage Δ
ChromeCi	`89.93% <94.00%> (+<0.01%)`	⬆️
Firefox	`89.92% <94.00%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot

Pull Request Overview

This PR introduces the new useFormControl hook to provide form control functionality in custom form components within a Form. It implements the hook and refactors associated modules and documentation to integrate the new functionality.

Implements the useFormControl hook with proper registration, value management, and event handling for form fields.
Refactors existing components (e.g., FormControl) to use the new hook.
Updates documentation and tests to illustrate and validate the new hook's usage.

Reviewed Changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/useFormControl/useFormControl.tsx	New hook implementation for managing form control behavior
src/useFormControl/test/utilsSpec.ts	Updated import path for nameToPath utility
src/useFormControl/index.tsx	Export updates for useFormControl and its types
src/useFormControl/hooks/useRegisterModel.ts	Changed register model function to be an exported function
src/useFormControl/hooks/useField.ts	Adjusted exports and made nestedField optional
src/index.tsx	Export updated for useFormControl hook
src/FormControl/FormControl.tsx	Refactored to use useFormControl for handling form control logic
src/Form/hooks/useFormValidate.ts	Updated import path for nameToPath utility
src/Form/FormContext.tsx	Modified onFieldChange signature to accept an optional event
Documentation files	Added and modified documentation to include useFormControl hook examples

Files not reviewed (1)

docs/component.config.json: Language not supported

Comments suppressed due to low confidence (1)

src/useFormControl/useFormControl.tsx:60

[nitpick] Consider updating this error message to be clearer and more concise. Avoid referencing a fixed React version (16.6.0+) since it may become outdated over time, and consider throwing an error instead of logging to the console to enforce proper usage.

if (!onFieldChange) {

feat(Form): add useFormControl hook

0f8fa62

simonguo requested review from myNameIsDu and Copilot May 6, 2025 11:17

Copilot AI reviewed May 6, 2025

View reviewed changes

src/useFormControl/useFormControl.tsx Outdated Show resolved Hide resolved

docs/pages/components/popover/en-US/index.md Show resolved Hide resolved

vercel bot deployed to Preview – rsuite-storybook May 6, 2025 11:18 View deployment

vercel bot deployed to Preview – rsuite-nextjs May 6, 2025 11:22 View deployment

test(useformcontrol): improve test coverage for uncovered code

97897f1

vercel bot deployed to Preview – rsuite-storybook May 7, 2025 01:48 View deployment

vercel bot deployed to Preview – rsuite-nextjs May 7, 2025 01:53 View deployment

test(useformcontrol): improve test coverage for uncovered code

6d67e9f

vercel bot deployed to Preview – rsuite-storybook May 7, 2025 02:20 View deployment

simonguo requested a review from Copilot May 7, 2025 02:24

Copilot AI reviewed May 7, 2025

View reviewed changes

vercel bot deployed to Preview – rsuite-nextjs May 7, 2025 02:26 View deployment

docs(form-validation): add step-by-step guide styles

e03df5f

vercel bot deployed to Preview – rsuite-storybook May 7, 2025 03:59 View deployment

vercel bot deployed to Preview – rsuite-nextjs May 7, 2025 04:05 View deployment

simonguo added this to the v6 milestone May 7, 2025

simonguo merged commit 3a66273 into next May 9, 2025
16 of 17 checks passed

simonguo deleted the feat/add-useformcontrol-hook branch May 9, 2025 03:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(Form): add useFormControl hook #4268

feat(Form): add useFormControl hook #4268

Uh oh!

simonguo commented May 6, 2025 •

edited

Loading

Uh oh!

codesandbox bot commented May 6, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

vercel bot commented May 6, 2025 •

edited

Loading

Uh oh!

codesandbox-ci bot commented May 6, 2025 •

edited

Loading

Uh oh!

codecov bot commented May 6, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Search code, repositories, users, issues, pull requests...

Uh oh!

feat(Form): add useFormControl hook #4268

feat(Form): add useFormControl hook #4268

Uh oh!

Conversation

simonguo commented May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Return Values

Example

Uh oh!

codesandbox bot commented May 6, 2025

Review or Edit in CodeSandbox

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

vercel bot commented May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codesandbox-ci bot commented May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

simonguo commented May 6, 2025 •

edited

Loading

vercel bot commented May 6, 2025 •

edited

Loading

codesandbox-ci bot commented May 6, 2025 •

edited

Loading

codecov bot commented May 6, 2025 •

edited

Loading