---
title: Form
subtitle: A native form element with consolidated error handling.
description: A high-quality, unstyled React form component with consolidated error handling.
---
> FineSoft Components documentation. Independent Stencil port; not the official Base UI website.
>
> React API text and `@base-ui/react` examples are upstream references. FineSoft Stencil examples use `finesoft-components`. Do not treat the two packages as interchangeable.
# Form
A high-quality, unstyled React form component with consolidated error handling.
## Demo
### Tailwind
This example shows how to implement the component using Tailwind CSS.
```tsx
/* docs-comparison.tsx */
import { StencilComparison } from 'docs/src/components/StencilComparison';
import ReactForm from './react-form';
import StencilForm from './stencil-form';
import { StencilFormView } from './stencil-form-view';
export default function FormComparison() {
return } stencil={} clientStencil={} />;
}
```
```tsx
/* react-form.tsx */
'use client';
import * as React from 'react';
import { Field } from '@base-ui/react/field';
import { Form } from '@base-ui/react/form';
import { Button } from '@base-ui/react/button';
export default function ExampleForm() {
const [errors, setErrors] = React.useState({});
const [loading, setLoading] = React.useState(false);
return (
);
}
async function submitForm(value: string) {
// Mimic a server response
await new Promise(resolve => {
setTimeout(resolve, 1000);
});
try {
const url = new URL(value);
if (url.hostname.endsWith('example.com')) {
return { error: 'The example domain is not allowed' };
}
} catch {
return { error: 'This is not a valid URL' };
}
return { success: true };
}
```
```tsx
/* stencil-form.tsx */
'use client';
import * as React from 'react';
import { StencilFormView } from './stencil-form-view';
export default function StencilForm() {
const [errors, setErrors] = React.useState({});
const [loading, setLoading] = React.useState(false);
return (
{
event.preventDefault();
const formData = new FormData(event.target as HTMLFormElement);
const value = formData.get('url') as string;
setLoading(true);
const response = await submitForm(value);
const serverErrors = {
url: response.error,
};
setErrors(serverErrors);
setLoading(false);
}}
loading={loading}
/>
);
}
async function submitForm(value: string) {
// Mimic a server response
await new Promise(resolve => {
setTimeout(resolve, 1000);
});
try {
const url = new URL(value);
if (url.hostname.endsWith('example.com')) {
return { error: 'The example domain is not allowed' };
}
} catch {
return { error: 'This is not a valid URL' };
}
return { success: true };
}
```
```tsx
/* stencil-form-view.tsx */
import type * as React from 'react';
import type { FormErrors } from 'finesoft-components/define-custom-elements';
interface StencilFormViewProps {
errors?: FormErrors;
loading?: boolean;
onSubmit?: React.FormEventHandler;
}
export function StencilFormView({ errors, loading = false, onSubmit }: StencilFormViewProps) {
return (
Homepage
Submit
);
}
```
### CSS Modules
This example shows how to implement the component using CSS Modules.
```css
/* index.module.css */
.Form {
display: flex;
flex-direction: column;
gap: 1rem;
width: 100%;
max-width: 16rem;
}
.Field {
display: flex;
flex-direction: column;
align-items: start;
gap: 0.25rem;
}
.Label {
font-size: 0.875rem;
line-height: 1.25rem;
font-weight: 700;
color: oklch(14.5% 0 0deg);
@media (prefers-color-scheme: dark) {
color: white;
}
}
.Input {
box-sizing: border-box;
padding: 0 0.5rem;
margin: 0;
border-radius: 0;
border: 1px solid oklch(14.5% 0 0deg);
width: 100%;
height: 2rem;
font-family: inherit;
font-size: 0.875rem;
line-height: 1.25rem;
font-weight: 400;
background-color: white;
color: oklch(14.5% 0 0deg);
@media (any-pointer: coarse) {
font-size: 1rem;
line-height: 1.5rem;
}
@media (prefers-color-scheme: dark) {
border: 1px solid white;
background-color: oklch(14.5% 0 0deg);
color: white;
}
&::placeholder {
color: oklch(55.6% 0 0deg);
@media (prefers-color-scheme: dark) {
color: oklch(70.8% 0 0deg);
}
}
&:focus {
outline: 2px solid oklch(14.5% 0 0deg);
outline-offset: -1px;
@media (prefers-color-scheme: dark) {
outline-color: white;
}
}
}
.Error {
font-size: 0.875rem;
line-height: 1.25rem;
color: oklch(50.5% 0.213 27.518deg);
@media (prefers-color-scheme: dark) {
color: oklch(70.4% 0.191 22.216deg);
}
}
.Button {
box-sizing: border-box;
display: flex;
align-items: center;
justify-content: center;
gap: 0.5rem;
height: 2rem;
padding: 0 0.75rem;
margin: 0;
outline: 0;
border: 1px solid oklch(14.5% 0 0deg);
border-radius: 0;
background-color: white;
font-family: inherit;
font-size: 0.875rem;
font-weight: 400;
line-height: 1;
white-space: nowrap;
color: oklch(14.5% 0 0deg);
-webkit-user-select: none;
user-select: none;
@media (prefers-color-scheme: dark) {
border: 1px solid white;
background-color: oklch(14.5% 0 0deg);
color: white;
}
@media (hover: hover) {
&:hover:not([data-disabled]) {
background-color: oklch(97% 0 0deg);
@media (prefers-color-scheme: dark) {
background-color: oklch(26.9% 0 0deg);
}
}
}
&:active:not([data-disabled]) {
background-color: oklch(92.2% 0 0deg);
@media (prefers-color-scheme: dark) {
background-color: oklch(37.1% 0 0deg);
}
}
&[data-disabled] {
color: oklch(55.6% 0 0deg);
border-color: oklch(55.6% 0 0deg);
@media (prefers-color-scheme: dark) {
color: oklch(70.8% 0 0deg);
border-color: oklch(70.8% 0 0deg);
}
}
&:focus-visible {
outline: 2px solid oklch(14.5% 0 0deg);
outline-offset: -1px;
@media (prefers-color-scheme: dark) {
outline-color: white;
}
}
}
```
```tsx
/* docs-comparison.tsx */
import { StencilComparison } from 'docs/src/components/StencilComparison';
import ReactForm from './react-form';
import StencilForm from './stencil-form';
import { StencilFormView } from './stencil-form-view';
export default function FormComparison() {
return } stencil={} clientStencil={} />;
}
```
```tsx
/* react-form.tsx */
'use client';
import * as React from 'react';
import { Field } from '@base-ui/react/field';
import { Form } from '@base-ui/react/form';
import { Button } from '@base-ui/react/button';
import styles from './index.module.css';
export default function ExampleForm() {
const [errors, setErrors] = React.useState({});
const [loading, setLoading] = React.useState(false);
return (
);
}
async function submitForm(value: string) {
// Mimic a server response
await new Promise(resolve => {
setTimeout(resolve, 1000);
});
try {
const url = new URL(value);
if (url.hostname.endsWith('example.com')) {
return { error: 'The example domain is not allowed' };
}
} catch {
return { error: 'This is not a valid URL' };
}
return { success: true };
}
```
```tsx
/* stencil-form.tsx */
'use client';
import * as React from 'react';
import { StencilFormView } from './stencil-form-view';
export default function StencilForm() {
const [errors, setErrors] = React.useState({});
const [loading, setLoading] = React.useState(false);
return (
{
event.preventDefault();
const formData = new FormData(event.target as HTMLFormElement);
const value = formData.get('url') as string;
setLoading(true);
const response = await submitForm(value);
const serverErrors = {
url: response.error,
};
setErrors(serverErrors);
setLoading(false);
}}
loading={loading}
/>
);
}
async function submitForm(value: string) {
// Mimic a server response
await new Promise(resolve => {
setTimeout(resolve, 1000);
});
try {
const url = new URL(value);
if (url.hostname.endsWith('example.com')) {
return { error: 'The example domain is not allowed' };
}
} catch {
return { error: 'This is not a valid URL' };
}
return { success: true };
}
```
```tsx
/* stencil-form-view.tsx */
import type * as React from 'react';
import type { FormErrors } from 'finesoft-components/define-custom-elements';
interface StencilFormViewProps {
errors?: FormErrors;
loading?: boolean;
onSubmit?: React.FormEventHandler;
}
export function StencilFormView({ errors, loading = false, onSubmit }: StencilFormViewProps) {
return (
Homepage
Submit
);
}
```
The Stencil comparison uses `fs-form` together with the migrated
[`fs-field-*`](/react/components/field.md) and [`fs-button`](/react/components/button.md)
elements. `fs-form` is a transparent custom-element host: it renders the native
`;
```
## Examples
### Submit with a Server Function
Forms using `useActionState` can be submitted with a [Server Function](https://react.dev/reference/react-dom/components/form#handle-form-submission-with-a-server-function) instead of `onSubmit`.
## Demo
### Tailwind
This example shows how to implement the component using Tailwind CSS.
```tsx
/* docs-comparison.tsx */
import { StencilComparison } from 'docs/src/components/StencilComparison';
import ReactForm from './react-form';
import StencilForm from './stencil-form';
import { StencilFormView } from './stencil-form-view';
export default function FormActionComparison() {
return } stencil={} clientStencil={} />;
}
```
```tsx
/* react-form.tsx */
'use client';
import * as React from 'react';
import { Field } from '@base-ui/react/field';
import { Form } from '@base-ui/react/form';
import { Button } from '@base-ui/react/button';
interface FormState {
serverErrors?: Form.Props['errors'];
}
export default function ActionStateForm() {
const [state, formAction, loading] = React.useActionState(submitForm, {});
return (
);
}
// Mark this as a Server Function with `'use server'` in a supporting framework like Next.js
async function submitForm(_previousState: FormState, formData: FormData) {
// Mimic a server response
await new Promise(resolve => {
setTimeout(resolve, 1000);
});
try {
const username = formData.get('username') as string | null;
if (username === 'admin') {
return { success: false, serverErrors: { username: "'admin' is reserved for system use" } };
}
// 50% chance the username is taken
const success = Math.random() > 0.5;
if (!success) {
return {
serverErrors: { username: `${username} is unavailable` },
};
}
} catch {
return { serverErrors: { username: 'A server error has occurred' } };
}
return {};
}
```
```tsx
/* stencil-form.tsx */
'use client';
import * as React from 'react';
import type { FormErrors } from 'finesoft-components/define-custom-elements';
import { StencilFormView } from './stencil-form-view';
interface FormState {
serverErrors?: FormErrors;
}
export default function StencilForm() {
const [state, formAction, loading] = React.useActionState(submitForm, {});
return React.startTransition(() => formAction(formData))} errors={state.serverErrors} loading={loading} />;
}
// Mark this as a Server Function with `'use server'` in a supporting framework like Next.js
async function submitForm(_previousState: FormState, formData: FormData) {
// Mimic a server response
await new Promise(resolve => {
setTimeout(resolve, 1000);
});
try {
const username = formData.get('username') as string | null;
if (username === 'admin') {
return { success: false, serverErrors: { username: "'admin' is reserved for system use" } };
}
// 50% chance the username is taken
const success = Math.random() > 0.5;
if (!success) {
return {
serverErrors: { username: `${username} is unavailable` },
};
}
} catch {
return { serverErrors: { username: 'A server error has occurred' } };
}
return {};
}
```
```tsx
/* stencil-form-view.tsx */
import type { FormAction, FormErrors } from 'finesoft-components/define-custom-elements';
interface StencilFormViewProps {
action?: FormAction;
errors?: FormErrors;
loading?: boolean;
}
export function StencilFormView({ action, errors, loading = false }: StencilFormViewProps) {
return (
Username
Submit
);
}
```
### CSS Modules
This example shows how to implement the component using CSS Modules.
```css
/* index.module.css */
.Form {
display: flex;
flex-direction: column;
gap: 1rem;
width: 100%;
max-width: 16rem;
}
.Field {
display: flex;
flex-direction: column;
align-items: start;
gap: 0.25rem;
}
.Label {
font-size: 0.875rem;
line-height: 1.25rem;
font-weight: 700;
color: oklch(14.5% 0 0deg);
@media (prefers-color-scheme: dark) {
color: white;
}
}
.Input {
box-sizing: border-box;
padding: 0 0.5rem;
margin: 0;
border-radius: 0;
border: 1px solid oklch(14.5% 0 0deg);
width: 100%;
height: 2rem;
font-family: inherit;
font-size: 0.875rem;
line-height: 1.25rem;
font-weight: 400;
background-color: white;
color: oklch(14.5% 0 0deg);
@media (any-pointer: coarse) {
font-size: 1rem;
line-height: 1.5rem;
}
@media (prefers-color-scheme: dark) {
border: 1px solid white;
background-color: oklch(14.5% 0 0deg);
color: white;
}
&::placeholder {
color: oklch(55.6% 0 0deg);
@media (prefers-color-scheme: dark) {
color: oklch(70.8% 0 0deg);
}
}
&:focus {
outline: 2px solid oklch(14.5% 0 0deg);
outline-offset: -1px;
@media (prefers-color-scheme: dark) {
outline-color: white;
}
}
}
.Error {
font-size: 0.875rem;
line-height: 1.25rem;
color: oklch(50.5% 0.213 27.518deg);
@media (prefers-color-scheme: dark) {
color: oklch(70.4% 0.191 22.216deg);
}
}
.Button {
box-sizing: border-box;
display: flex;
align-items: center;
justify-content: center;
gap: 0.5rem;
height: 2rem;
padding: 0 0.75rem;
margin: 0;
outline: 0;
border: 1px solid oklch(14.5% 0 0deg);
border-radius: 0;
background-color: white;
font-family: inherit;
font-size: 0.875rem;
font-weight: 400;
line-height: 1;
white-space: nowrap;
color: oklch(14.5% 0 0deg);
-webkit-user-select: none;
user-select: none;
@media (prefers-color-scheme: dark) {
border: 1px solid white;
background-color: oklch(14.5% 0 0deg);
color: white;
}
@media (hover: hover) {
&:hover:not([data-disabled]) {
background-color: oklch(97% 0 0deg);
@media (prefers-color-scheme: dark) {
background-color: oklch(26.9% 0 0deg);
}
}
}
&:active:not([data-disabled]) {
background-color: oklch(92.2% 0 0deg);
@media (prefers-color-scheme: dark) {
background-color: oklch(37.1% 0 0deg);
}
}
&[data-disabled] {
color: oklch(55.6% 0 0deg);
border-color: oklch(55.6% 0 0deg);
@media (prefers-color-scheme: dark) {
color: oklch(70.8% 0 0deg);
border-color: oklch(70.8% 0 0deg);
}
}
&:focus-visible {
outline: 2px solid oklch(14.5% 0 0deg);
outline-offset: -1px;
@media (prefers-color-scheme: dark) {
outline-color: white;
}
}
}
```
```tsx
/* docs-comparison.tsx */
import { StencilComparison } from 'docs/src/components/StencilComparison';
import ReactForm from './react-form';
import StencilForm from './stencil-form';
import { StencilFormView } from './stencil-form-view';
export default function FormActionComparison() {
return } stencil={} clientStencil={} />;
}
```
```tsx
/* react-form.tsx */
'use client';
import * as React from 'react';
import { Field } from '@base-ui/react/field';
import { Form } from '@base-ui/react/form';
import { Button } from '@base-ui/react/button';
import styles from './index.module.css';
interface FormState {
serverErrors?: Form.Props['errors'];
}
export default function ActionStateForm() {
const [state, formAction, loading] = React.useActionState(submitForm, {});
return (
);
}
// Mark this as a Server Function with `'use server'` in a supporting framework like Next.js
async function submitForm(_previousState: FormState, formData: FormData) {
// Mimic a server response
await new Promise(resolve => {
setTimeout(resolve, 1000);
});
try {
const username = formData.get('username') as string | null;
if (username === 'admin') {
return { success: false, serverErrors: { username: "'admin' is reserved for system use" } };
}
// 50% chance the username is taken
const success = Math.random() > 0.5;
if (!success) {
return {
serverErrors: { username: `${username} is unavailable` },
};
}
} catch {
return { serverErrors: { username: 'A server error has occurred' } };
}
return {};
}
```
```tsx
/* stencil-form.tsx */
'use client';
import * as React from 'react';
import type { FormErrors } from 'finesoft-components/define-custom-elements';
import { StencilFormView } from './stencil-form-view';
interface FormState {
serverErrors?: FormErrors;
}
export default function StencilForm() {
const [state, formAction, loading] = React.useActionState(submitForm, {});
return React.startTransition(() => formAction(formData))} loading={loading} />;
}
// Mark this as a Server Function with `'use server'` in a supporting framework like Next.js
async function submitForm(_previousState: FormState, formData: FormData) {
// Mimic a server response
await new Promise(resolve => {
setTimeout(resolve, 1000);
});
try {
const username = formData.get('username') as string | null;
if (username === 'admin') {
return { success: false, serverErrors: { username: "'admin' is reserved for system use" } };
}
// 50% chance the username is taken
const success = Math.random() > 0.5;
if (!success) {
return {
serverErrors: { username: `${username} is unavailable` },
};
}
} catch {
return { serverErrors: { username: 'A server error has occurred' } };
}
return {};
}
```
```tsx
/* stencil-form-view.tsx */
import type { FormAction, FormErrors } from 'finesoft-components/define-custom-elements';
interface StencilFormViewProps {
action?: FormAction;
errors?: FormErrors;
loading?: boolean;
}
export function StencilFormView({ action, errors, loading = false }: StencilFormViewProps) {
return (
Username
Submit
);
}
```
### Submit form values as a JavaScript object
You can use `onFormSubmit` instead of the native `onSubmit` to access form values as a JavaScript object. This is useful when you need to transform the values before submission, or integrate with 3rd party APIs.
```tsx title="Submission using onFormSubmit"
);
}
```
```tsx
/* stencil-form.tsx */
'use client';
import * as React from 'react';
import { z } from 'zod';
import type { FormValues } from 'finesoft-components/define-custom-elements';
import { StencilFormView } from './stencil-form-view';
const schema = z.object({
name: z.string().min(1, 'Name is required'),
age: z.coerce.number('Age must be a number').positive('Age must be a positive number'),
});
async function submitForm(formValues: FormValues) {
const result = schema.safeParse(formValues);
if (!result.success) {
return {
errors: z.flattenError(result.error).fieldErrors,
};
}
return {
errors: {},
};
}
export default function StencilForm() {
const [errors, setErrors] = React.useState({});
return (
{
const response = await submitForm(formValues);
setErrors(response.errors);
}}
/>
);
}
```
```tsx
/* stencil-form-view.tsx */
import type { FormErrors, FormSubmitHandler } from 'finesoft-components/define-custom-elements';
interface StencilFormViewProps {
errors?: FormErrors;
formSubmit?: FormSubmitHandler;
}
export function StencilFormView({ errors, formSubmit }: StencilFormViewProps) {
return (
Name
Age
Submit
);
}
```
### CSS Modules
This example shows how to implement the component using CSS Modules.
```css
/* index.module.css */
.Form {
display: flex;
flex-direction: column;
gap: 1rem;
width: 100%;
max-width: 16rem;
}
.Field {
display: flex;
flex-direction: column;
align-items: start;
gap: 0.25rem;
}
.Label {
font-size: 0.875rem;
line-height: 1.25rem;
font-weight: 700;
color: oklch(14.5% 0 0deg);
@media (prefers-color-scheme: dark) {
color: white;
}
}
.Input {
box-sizing: border-box;
padding: 0 0.5rem;
margin: 0;
border-radius: 0;
border: 1px solid oklch(14.5% 0 0deg);
width: 100%;
height: 2rem;
font-family: inherit;
font-size: 0.875rem;
line-height: 1.25rem;
font-weight: 400;
background-color: white;
color: oklch(14.5% 0 0deg);
@media (any-pointer: coarse) {
font-size: 1rem;
line-height: 1.5rem;
}
@media (prefers-color-scheme: dark) {
border: 1px solid white;
background-color: oklch(14.5% 0 0deg);
color: white;
}
&::placeholder {
color: oklch(55.6% 0 0deg);
@media (prefers-color-scheme: dark) {
color: oklch(70.8% 0 0deg);
}
}
&:focus {
outline: 2px solid oklch(14.5% 0 0deg);
outline-offset: -1px;
@media (prefers-color-scheme: dark) {
outline-color: white;
}
}
}
.Error {
font-size: 0.875rem;
line-height: 1.25rem;
color: oklch(50.5% 0.213 27.518deg);
@media (prefers-color-scheme: dark) {
color: oklch(70.4% 0.191 22.216deg);
}
}
.Button {
box-sizing: border-box;
display: flex;
align-items: center;
justify-content: center;
gap: 0.5rem;
height: 2rem;
padding: 0 0.75rem;
margin: 0;
outline: 0;
border: 1px solid oklch(14.5% 0 0deg);
border-radius: 0;
background-color: white;
font-family: inherit;
font-size: 0.875rem;
font-weight: 400;
line-height: 1;
white-space: nowrap;
color: oklch(14.5% 0 0deg);
-webkit-user-select: none;
user-select: none;
@media (prefers-color-scheme: dark) {
border: 1px solid white;
background-color: oklch(14.5% 0 0deg);
color: white;
}
@media (hover: hover) {
&:hover:not([data-disabled]) {
background-color: oklch(97% 0 0deg);
@media (prefers-color-scheme: dark) {
background-color: oklch(26.9% 0 0deg);
}
}
}
&:active:not([data-disabled]) {
background-color: oklch(92.2% 0 0deg);
@media (prefers-color-scheme: dark) {
background-color: oklch(37.1% 0 0deg);
}
}
&[data-disabled] {
color: oklch(55.6% 0 0deg);
border-color: oklch(55.6% 0 0deg);
@media (prefers-color-scheme: dark) {
color: oklch(70.8% 0 0deg);
border-color: oklch(70.8% 0 0deg);
}
}
&:focus-visible {
outline: 2px solid oklch(14.5% 0 0deg);
outline-offset: -1px;
@media (prefers-color-scheme: dark) {
outline-color: white;
}
}
}
```
```tsx
/* docs-comparison.tsx */
import { StencilComparison } from 'docs/src/components/StencilComparison';
import ReactForm from './react-form';
import StencilForm from './stencil-form';
import { StencilFormView } from './stencil-form-view';
export default function FormComparison() {
return } stencil={} clientStencil={} />;
}
```
```tsx
/* react-form.tsx */
'use client';
import * as React from 'react';
import { z } from 'zod';
import { Field } from '@base-ui/react/field';
import { Form } from '@base-ui/react/form';
import { Button } from '@base-ui/react/button';
import styles from './index.module.css';
const schema = z.object({
name: z.string().min(1, 'Name is required'),
age: z.coerce.number('Age must be a number').positive('Age must be a positive number'),
});
async function submitForm(formValues: Form.Values) {
const result = schema.safeParse(formValues);
if (!result.success) {
return {
errors: z.flattenError(result.error).fieldErrors,
};
}
return {
errors: {},
};
}
export default function Page() {
const [errors, setErrors] = React.useState({});
return (
);
}
```
```tsx
/* stencil-form.tsx */
'use client';
import * as React from 'react';
import { z } from 'zod';
import type { FormValues } from 'finesoft-components/define-custom-elements';
import { StencilFormView } from './stencil-form-view';
const schema = z.object({
name: z.string().min(1, 'Name is required'),
age: z.coerce.number('Age must be a number').positive('Age must be a positive number'),
});
async function submitForm(formValues: FormValues) {
const result = schema.safeParse(formValues);
if (!result.success) {
return {
errors: z.flattenError(result.error).fieldErrors,
};
}
return {
errors: {},
};
}
export default function StencilForm() {
const [errors, setErrors] = React.useState({});
return (
{
const response = await submitForm(formValues);
setErrors(response.errors);
}}
/>
);
}
```
```tsx
/* stencil-form-view.tsx */
import type { FormErrors, FormSubmitHandler } from 'finesoft-components/define-custom-elements';
interface StencilFormViewProps {
errors?: FormErrors;
formSubmit?: FormSubmitHandler;
}
export function StencilFormView({ errors, formSubmit }: StencilFormViewProps) {
return (
Name
Age
Submit
);
}
```
## API reference
### Form
A native form element with consolidated error handling.
Renders a `