formController tools

The formController exposes various methods for managing forms. Each method has a specific role — together they manage the form's lifecycle. useRegister registers inputs and wires event handlers; useFields reads field values, errors, and meta. Use setValues and setErrors to inject external data or manipulate state, and handleSubmit to validate and run callbacks on successful submission. These tools enable declarative, maintainable form logic and improve developer productivity and code quality.

const {
  initValue,
  useRegister,
  useFields,
  setValues,
  setErrors,
  handleSubmit,
  handleServerAction
} = formController

useRegister#

useRegister registers an input with the Sicilian controller and auto-connects event handlers. As the type definitions below show, it supports many input types and provides type safety in TypeScript. The ExtractKeys<T> variant restricts allowed field names to those defined in initValue or validator, preventing typos. The string variant allows dynamic field addition. For radio, value is required to distinguish radio buttons sharing the same name. You may also pass a validate object per-field in the options.

type TRegister<T extends InitState> = {
  // For radio type – ExtractKeys<T> version
  <K extends ExtractKeys<T>>(name: K, options: RegisterRadioOptions<T>): IRegister<T>,
  // For non-radio types – ExtractKeys<T> version
  <K extends ExtractKeys<T>>(name: K, options?: RegisterOptions<T>): IRegister<T>,
  
  // For radio type – string version
  (name: string, options: RegisterRadioOptions<T>): IRegister<T>,
  // For non-radio types – string version
  (name: string, options?: RegisterOptions<T>): IRegister<T>;
}

The object returned by useRegister (the IRegister interface) provides props and handlers to integrate with React inputs. onChange, onBlur, and onFocus update form state and optionally trigger validation. SicilianEvent handles DOM and custom events. name and id identify fields; type, checked, and value reflect native input props. Apply them to JSX with the spread syntax {...useRegister('email')} to reduce boilerplate.

export interface IRegister<T extends InitState> {
  onChange: (e: SicilianEvent) => void
  onFocus: (e: SicilianEvent) => void
  onBlur: (e: SicilianEvent) => void
  name: ExtractKeys<T> | string
  id: ExtractKeys<T> | string
  type: HTMLInputElement["type"]
  value?: string
  checked?: boolean
}

Values and Errors#

useFields provides access to current values and errors along with field meta. It can subscribe to the entire form or a specific field. setStore and getStore expose low-level store access for advanced scenarios. Note:

Calling useFields() without arguments subscribes to all fields, which can trigger broader re-renders. Prefer useFields(name) for fine-grained subscriptions.

useFields: TUseFields<T>;
setValues: IStore<T>["setStore"];
setErrors: IStore<{ [key in keyof T]: string }>["setStore"];

export type TUseFields<T extends InitState> = {
  (): AllFieldsState<T>;
  <K extends ExtractKeys<T>>(name: K): FieldState<T, K>;
  (name: string): FieldStateValue;
}

export type FieldStateValue = {
  value: StoreValue | undefined;
  error: string;
  touched: boolean;
  dirty: boolean;
  isValid: boolean;
}

export interface IStore<T> {
  ...
  setStore: (nextState: Partial<T> & { [x: string]: string | boolean | FileList }) => void;
  ...
}

setValues and setErrors update parts of the form state or error state, enabling fine-grained updates useful for performance optimization.

const { setValues } = ArticleFormController
 
const { data } = useQuery({
  queryKey: ["review", reviewId],
  queryFn: getReview(reviewId)
  }
});
 
useEffect(() => {
  setValues({
    title: data?.title ?? "",
    author: data?.author ?? "",
    description: data?.description ?? ""
  });
}, [data]);

handleSubmit#

handleSubmit accepts a callback invoked with the current formState and the event object. It internally calls e.preventDefault() to prevent navigation on form submit.

<form
  onSubmit={handleSubmit(async (data, e) => {
    const res = await fetch("URL", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    });
  })}
>

You can implement submit logic by manually reading formState via useFields(), but handleSubmit offers additional safety and conveniences.

• If any unresolved error message remains, handleSubmit cancels submission to prevent unwanted data from going to the backend.
• Similarly, if all inputs managed by the formController are empty, submission is canceled to avoid accidental HTTP requests.

Even if clearFormOn includes ["submit"], the form will not clear if submission fails.

handleServerAction#

handleServerAction handles server actions or server functions to submit form data and process responses. It integrates with server-side async functions and lets you provide a server action function that receives form data and an event. Validation runs before the server action is invoked; if validation fails, the server action won't be called. Optionally provide a callback to handle success or error responses from the server.

export function FeedbackModal() {
  const [state, execute, isPending] = useActionState(postFeedback);
  
  useEffect(() => {
    if (state?.message) {
      grunfeld.clear();
      toast.success("피드백이 제출되었습니다.");
    }
  }, [state?.message]);

  return <Form
    action={handleServerAction(execute)}
    className="flex flex-col w-full gap-24 overflow-y-scroll md:min-w-400"
  >
}

Typical server action functions accept a FormData argument, but handleServerAction converts form data to an object before calling the server action, making server-side handling easier and avoiding direct FormData manipulation. The event object is also passed for additional context.

"use server";

import { FeedbackTypeKr } from "@/shared/types";
import { getCookieValue } from "@/shared/utils/cookieUtils";
import { getEnumKeyByValue } from "@/shared/utils/enumUtils";
import { fetcher } from "@/shared/utils/fetcher";

export async function postFeedback(
  prev: unknown,
  {
    type,
    message,
  }: {
    type: FeedbackTypeKr | "";
    message: string;
  }
) {
  try {
    return await fetcher.post(
      `feedback`,
      {
        body: {
          type: getEnumKeyByValue(type, FeedbackTypeKr),
          message,
        },
      },
      {
        headers: {
          Cookie: await getCookieValue(),
        },
      }
    );
  } catch (error) {
    console.error("Error occurred while starting interview:", error);
  }
}

This design simplifies form submission and server communication using handleServerAction.

useFields#

The useFields hook allows selective subscription to individual field states. Using this hook, you can subscribe to specific field values or errors instead of the entire form state, preventing unnecessary re-renders and optimizing performance.

export default function MySimpleForm() {
  const { useRegister, handleSubmit, useFields } = useForm({
    initValue: {
      name: '',
      email: ''
    },
    validator: {
      name: {
        required: { required: true, message: 'name is required' }
      },
      email: {
        required: { required: true, message: 'email is required' },
        RegExp: {
          RegExp: /^[a-zA-Z0-9+-_.]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$/,
          message: 'email format is invalid'
        }
      }
    }
  });

  const onSubmit = (data) => {
    console.log('data:', data);
  };

  // useFields를 사용하여 개별 필드 상태 구독
  const nameField = useFields('name');
  const emailField = useFields('email');

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <label htmlFor="name">name:</label>
        <input id="name" {...useRegister('name', { type: 'text' })} />
        {/* nameField.error를 통해 해당 필드의 오류만 접근 */}
        {nameField.error}
      </div>

      <div>
        <label htmlFor="email">email:</label>
        <input id="email" {...useRegister('email', { type: 'email' })} />
        {/* emailField.error를 통해 해당 필드의 오류만 접근 */}
        {emailField.error}
      </div>

      <button type="submit">login</button>
    </form>
  );
}

The useFields hook takes a field name as an argument and returns a state object for that field. The returned object includes value, error, touched, dirty, and isValid. This allows components to use only the necessary field information without directly accessing the global form state.

• Performance optimization: useFields(name) subscribes only to a specific field, so components re-render only when that field changes. This effectively prevents unnecessary re-renders caused by changes in overall form state.
• Type safety: In TypeScript environments, useFields provides accurate type inference based on field names. Using incorrect field names causes compile-time errors, preventing runtime errors in advance.
• Convenient usage: The state object returned by useFields contains value, error, and meta for the field, allowing you to display status without separate state management logic.