Component reference
Form
Typed values, validation and submit state with useForm.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Loading the interactive example?
Width adapts to the available space
"use client";
import { useState } from "react";
import { Button, Form, FormError, FormSubmit, Input, useForm } from "@pimolu/react";
export function FormExample() {
const [message, setMessage] = useState("");
const form = useForm({
defaultValues: { name: "" },
validate: (values) => values.name.trim()
? {}
: {
name: "Enter your name to continue."
},
onSubmit: (values) => { setMessage(`Welcome, ${values.name.trim()}. This example stays on your device.`); },
});
return (
<Form form={form} className="space-y-5">
<Input label="Your name" {...form.register("name")} fullWidth />
<FormError name="name" />
<div className="flex flex-wrap gap-3">
<FormSubmit>Join the workspace</FormSubmit>
<Button
appearance="outline"
onClick={() => { form.reset(); setMessage(""); }}
>
Reset
</Button>
</div>
<p role="status">{message}</p>
</Form>
);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Validation and async submit
validate returns a map of messages. When it finds one, onSubmit is never called; as soon as a field changes, its message is cleared.
Prefill, reset and inspect
setValues merges several fields at once, reset returns to defaultValues and clears every error. values is a plain object you can read at any time.
Native constraints
noValidate defaults to true so the component owns the error UI. Set it to false to let the browser enforce required, type and pattern too.
Usage
Create a flat defaultValues object and return field messages from validate to block submission. FormSubmit reflects isSubmitting; FormError belongs inside Form.
register reads native onChange values. For the styled Select, use form.values and form.setValue with onValueChange instead of relying on native onChange. Submission errors from a remote service remain your application's responsibility.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
UseFormOptions
Type source| Name | Type | Default | Description |
|---|---|---|---|
defaultValuesRequired | T | — | Initial values; also the values restored by `reset()`. |
validate | FormValidate<T> | undefined | — | Whole-form validation. Return a map of messages to block submit. |
onSubmit | FormSubmitHandler<T> | undefined | — | Called with the current values when the form is valid. |
defaultValuesRequiredTNo default extracted.
Initial values; also the values restored by `reset()`.
validateFormValidate<T> | undefinedNo default extracted.
Whole-form validation. Return a map of messages to block submit.
onSubmitFormSubmitHandler<T> | undefinedNo default extracted.
Called with the current values when the form is valid.
PimoluFormRegistration
Type source| Name | Type | Default | Description |
|---|---|---|---|
nameRequired | string | — | Public Pimolu prop; see the source declaration for details. |
value | string | number | readonly string[] | undefined | — | Public Pimolu prop; see the source declaration for details. |
checked | boolean | undefined | — | Public Pimolu prop; see the source declaration for details. |
onChangeRequired | (event: ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void | — | Public Pimolu prop; see the source declaration for details. |
aria-invalid | true | undefined | — | Public Pimolu prop; see the source declaration for details. |
aria-describedby | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
nameRequiredstringNo default extracted.
Public Pimolu prop; see the source declaration for details.
valuestring | number | readonly string[] | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
checkedboolean | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
onChangeRequired(event: ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => voidNo default extracted.
Public Pimolu prop; see the source declaration for details.
aria-invalidtrue | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
aria-describedbystring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
UseFormReturn
Type source| Name | Type | Default | Description |
|---|---|---|---|
valuesRequired | T | — | Current values, updated by `setValue` and `register`. |
errorsRequired | Partial<Record<Extract<keyof T, string>, string>> | — | Current validation messages, keyed by field name. |
isSubmittingRequired | boolean | — | True while an async `onSubmit` is pending. |
formIdRequired | string | — | Stable id prefix shared with `FormError`. |
setValueRequired | <K extends Extract<keyof T, string>>(name: K, value: T[K]) => void | — | Set one field and clear its error. |
setValuesRequired | (values: Partial<T>) => void | — | Merge several values and clear their errors. |
setErrorRequired | (name: Extract<keyof T, string>, message?: string) => void | — | Set or clear one field error programmatically. |
clearErrorsRequired | (name?: Extract<keyof T, string>) => void | — | Clear every error, or only one field. |
registerRequired | <K extends Extract<keyof T, string>>(name: K) => PimoluFormRegistration | — | Props that bind a native or Pimolu control to a field. |
handleSubmitRequired | (event?: FormEvent<HTMLFormElement>) => Promise<boolean> | — | Validate, then submit. Returns whether the form was valid. |
resetRequired | (nextValues?: Partial<T>) => void | — | Restore the initial values, or merge new ones. |
valuesRequiredTNo default extracted.
Current values, updated by `setValue` and `register`.
errorsRequiredPartial<Record<Extract<keyof T, string>, string>>No default extracted.
Current validation messages, keyed by field name.
isSubmittingRequiredbooleanNo default extracted.
True while an async `onSubmit` is pending.
formIdRequiredstringNo default extracted.
Stable id prefix shared with `FormError`.
setValueRequired<K extends Extract<keyof T, string>>(name: K, value: T[K]) => voidNo default extracted.
Set one field and clear its error.
setValuesRequired(values: Partial<T>) => voidNo default extracted.
Merge several values and clear their errors.
setErrorRequired(name: Extract<keyof T, string>, message?: string) => voidNo default extracted.
Set or clear one field error programmatically.
clearErrorsRequired(name?: Extract<keyof T, string>) => voidNo default extracted.
Clear every error, or only one field.
registerRequired<K extends Extract<keyof T, string>>(name: K) => PimoluFormRegistrationNo default extracted.
Props that bind a native or Pimolu control to a field.
handleSubmitRequired(event?: FormEvent<HTMLFormElement>) => Promise<boolean>No default extracted.
Validate, then submit. Returns whether the form was valid.
resetRequired(nextValues?: Partial<T>) => voidNo default extracted.
Restore the initial values, or merge new ones.
PimoluFormProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
formRequired | UseFormReturn<T> | — | The value returned by `useForm`. |
noValidate | boolean | undefined | true | Disable the browser validation UI. Defaults to true. |
children | ReactNode | "Submit" | Public Pimolu prop; see the source declaration for details. |
onChange | ChangeEventHandler<HTMLFormElement, Element> | undefined | — | Standard React/HTML attribute. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
onClick | MouseEventHandler<HTMLFormElement> | undefined | — | Standard React/HTML attribute. |
name | string | undefined | — | Standard React/HTML attribute. |
formRequiredUseFormReturn<T>No default extracted.
The value returned by `useForm`.
noValidateboolean | undefinedDefault: true
Disable the browser validation UI. Defaults to true.
childrenReactNodeDefault: "Submit"
Public Pimolu prop; see the source declaration for details.
onChangeChangeEventHandler<HTMLFormElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
onClickMouseEventHandler<HTMLFormElement> | undefinedNo default extracted.
Standard React/HTML attribute.
namestring | undefinedNo default extracted.
Standard React/HTML attribute.
PimoluFormErrorProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
nameRequired | string | — | Registered field name. |
className | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
nameRequiredstringNo default extracted.
Registered field name.
classNamestring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
PimoluFormSubmitProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
children | ReactNode | "Submit" | Public Pimolu prop; see the source declaration for details. |
onChange | ChangeEventHandler<HTMLButtonElement, Element> | undefined | — | Standard React/HTML attribute. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
onClick | MouseEventHandler<HTMLButtonElement> | undefined | — | Standard React/HTML attribute. |
variant | "primary" | "secondary" | "neutral" | "success" | "warning" | "danger" | undefined | — | Variant exposed by this component. |
appearance | "solid" | "soft" | "outline" | "ghost" | "link" | "dashed" | "glass" | "elevated" | "glow" | "text" | undefined | — | Visual treatment of the control or surface. |
size | "xs" | "sm" | "md" | "lg" | "xl" | "xxl" | undefined | — | Component size. |
radius | "sm" | "md" | "lg" | "none" | "full" | undefined | — | Corner-radius treatment. |
disabled | boolean | undefined | — | Standard React/HTML attribute. |
name | string | undefined | — | Standard React/HTML attribute. |
value | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
startIcon | ReactNode | — | Decorative content before the label or input. |
endIcon | ReactNode | — | Decorative content after the label or input. |
fullWidth | boolean | undefined | — | Use the available width of the parent. |
iconOnly | boolean | undefined | — | Render an icon-only action. Provide an accessible name with aria-label. |
childrenReactNodeDefault: "Submit"
Public Pimolu prop; see the source declaration for details.
onChangeChangeEventHandler<HTMLButtonElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
onClickMouseEventHandler<HTMLButtonElement> | undefinedNo default extracted.
Standard React/HTML attribute.
variant"primary" | "secondary" | "neutral" | "success" | "warning" | "danger" | undefinedNo default extracted.
Variant exposed by this component.
appearance"solid" | "soft" | "outline" | "ghost" | "link" | "dashed" | "glass" | "elevated" | "glow" | "text" | undefinedNo default extracted.
Visual treatment of the control or surface.
size"xs" | "sm" | "md" | "lg" | "xl" | "xxl" | undefinedNo default extracted.
Component size.
radius"sm" | "md" | "lg" | "none" | "full" | undefinedNo default extracted.
Corner-radius treatment.
disabledboolean | undefinedNo default extracted.
Standard React/HTML attribute.
namestring | undefinedNo default extracted.
Standard React/HTML attribute.
valuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
startIconReactNodeNo default extracted.
Decorative content before the label or input.
endIconReactNodeNo default extracted.
Decorative content after the label or input.
fullWidthboolean | undefinedNo default extracted.
Use the available width of the parent.
iconOnlyboolean | undefinedNo default extracted.
Render an icon-only action. Provide an accessible name with aria-label.
Accessibility
- Associate each field with a visible label and keep FormError beside it.
- register connects error descriptions and invalid state. The current hook does not automatically move focus to the first invalid field; decide how your form should handle that.