---
title: Forms
subtitle: A guide to building forms with Base UI components.
description: A guide to building forms with Base UI components.
---
> 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.
# Forms
A guide to building forms with Base UI components.
Base UI form control components extend the native [constraint validation API](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#the-constraint-validation-api) so you can build forms for collecting user input or providing control over an interface. They also integrate seamlessly with third-party libraries like [React Hook Form](/react/handbook/forms.md) and [TanStack Form](/react/handbook/forms.md).
## Demo
### Component theme
The Stencil example uses the built-in component theme. The frozen React comparison retains its original Tailwind styling.
```tsx
/* docs-comparison.tsx */
import { StencilComparison } from 'docs/src/components/StencilComparison';
import ReactExample from './react-hero';
import StencilExample from './docs-themed-preview';
import { formHTML, configureForm } from './stencil-form';
export default function Comparison() {
const options = { themed: true };
return (
}
stencil={null}
renderSource={() => formHTML(options)}
beforeHydrate={document => configureForm(document, options)}
clientStencil={}
/>
);
}
```
```tsx
/* react-hero.tsx */
'use client';
import * as React from 'react';
import { Button } from './button';
import { CheckboxGroup } from './checkbox-group';
import { Form } from './form';
import { RadioGroup } from './radio-group';
import { ToastProvider, useToastManager } from './toast';
import * as Autocomplete from './autocomplete';
import * as Checkbox from './checkbox';
import * as Combobox from './combobox';
import * as Field from './field';
import * as Fieldset from './fieldset';
import * as NumberField from './number-field';
import * as Radio from './radio';
import * as Select from './select';
import * as Slider from './slider';
import * as Switch from './switch';
function ExampleForm() {
const toastManager = useToastManager();
return (
);
}
export default function App() {
return (
);
}
function CaretUpDownIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
function CheckIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
function PlusIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
function MinusIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
function cartesian(...arrays: T): string[][] {
return arrays.reduce((acc, curr) => acc.flatMap(a => curr.map(b => [...a, b])), [[]]);
}
const REGIONS = cartesian(['us', 'eu', 'ap'], ['central', 'east', 'west'], ['1', '2', '3']).map(part => part.join('-'));
interface Image {
url: string;
name: string;
}
/* prettier-ignore */
const IMAGES: Image[] = ['nginx:1.29-alpine', 'node:22-slim', 'postgres:18', 'redis:8.2.2-alpine'].map((name) => ({
url: `docker.io/library/${name}`,
name,
}));
const SERVER_TYPES = [
{ label: 'Select server type', value: null },
...cartesian(['t', 'm'], ['1', '2'], ['small', 'medium', 'large']).map(part => {
const value = part.join('.').replace('.', '');
return { label: value, value };
}),
];
```
```tsx
/* docs-themed-preview.tsx */
'use client';
import { NativeStencilPreview } from 'docs/src/components/NativeStencilPreview';
import { mount } from './stencil-themed-hero';
export default function Preview() {
return ;
}
```
```ts
/* stencil-form.ts */
import type { Components } from 'finesoft-components';
export interface FormValues {
serverName: string;
region: string | null;
containerImage: string;
serverType: string | null;
numOfInstances: number | null;
scalingThreshold: number[];
storageType: 'ssd' | 'hdd';
restartOnFailure: boolean;
allowedNetworkProtocols: string[];
}
export const defaultValues: FormValues = {
serverName: '',
region: null,
containerImage: '',
serverType: null,
numOfInstances: null,
scalingThreshold: [0.2, 0.8],
storageType: 'ssd',
restartOnFailure: true,
allowedNetworkProtocols: [],
};
export const fieldNames = Object.keys(defaultValues) as Array;
export interface FormOptions {
externalValidation?: boolean;
nativeForm?: boolean;
themed?: boolean;
}
function cartesian(...arrays: string[][]): string[][] {
return arrays.reduce((acc, curr) => acc.flatMap(a => curr.map(b => [...a, b])), [[]]);
}
const REGIONS = cartesian(['us', 'eu', 'ap'], ['central', 'east', 'west'], ['1', '2', '3']).map(part => part.join('-'));
const IMAGES = ['nginx:1.29-alpine', 'node:22-slim', 'postgres:18', 'redis:8.2.2-alpine'].map(name => ({ name, url: `docker.io/library/${name}` }));
const SERVER_TYPES = [
{ label: 'Select server type', value: null },
...cartesian(['t', 'm'], ['1', '2'], ['small', 'medium', 'large']).map(part => {
const value = part.join('.').replace('.', '');
return { label: value, value };
}),
];
// This same Web Components declaration is used by the browser and by Stencil SSR.
// The framework integrations below only exchange public properties and events.
export function formHTML(options: FormOptions = {}): string {
if (options.themed) return themedFormHTML(options);
const { nativeForm = false } = options;
const html = `
Server nameMust be 3 or more characters long
Region
No matches
${REGIONS.map(
region => `
${region}
`,
).join('')}Container imageEnter a registry URL with optional tags${IMAGES.map(
image => `
${image.name}${image.url}
`,
).join('')}
Launch server
`;
return nativeForm ? html.replaceAll('fs-form', 'form') : html;
}
function themedFormHTML({ nativeForm = false }: FormOptions = {}): string {
const html = `
Server nameMust be 3 or more characters long
Region
No matches
${REGIONS.map(
region => `
${region}
`,
).join('')}Container imageEnter a registry URL with optional tags${IMAGES.map(
image => `
${image.name}${image.url}
`,
).join('')}
Launch server
`;
return nativeForm ? html.replaceAll('fs-form', 'form') : html;
}
function themedFormHTML({ nativeForm = false }: FormOptions = {}): string {
const html = `
Server nameMust be 3 or more characters long
Region
No matches
${REGIONS.map(
region => `
${region}
`,
).join('')}Container imageEnter a registry URL with optional tags${IMAGES.map(
image => `
${image.name}${image.url}
`,
).join('')}
: null}
);
}
export function List({ className, ...props }: Combobox.List.Props) {
return (
);
}
export function Item({ className, ...props }: Combobox.Item.Props) {
return (
);
}
export function ItemIndicator({ className, ...props }: Combobox.ItemIndicator.Props) {
return ;
}
export function CaretDownIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
function XIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
```
```tsx
/* field.tsx */
import * as React from 'react';
import clsx from 'clsx';
import { Field } from '@base-ui/react/field';
export function Root({ className, ...props }: Field.Root.Props) {
return ;
}
export function Label({ className, ...props }: Field.Label.Props) {
return (
);
}
export function Description({ className, ...props }: Field.Description.Props) {
return ;
}
export const Control = React.forwardRef(function FieldControl(
{ className, ...props }: Field.Control.Props,
forwardedRef: React.ForwardedRef,
) {
return (
);
});
export function Error({ className, ...props }: Field.Error.Props) {
return ;
}
export function Item(props: Field.Item.Props) {
return ;
}
```
```tsx
/* fieldset.tsx */
import * as React from 'react';
import clsx from 'clsx';
import { Fieldset } from '@base-ui/react/fieldset';
export function Root(props: Fieldset.Root.Props) {
return ;
}
export function Legend({ className, ...props }: Fieldset.Legend.Props) {
return ;
}
```
```tsx
/* number-field.tsx */
import * as React from 'react';
import clsx from 'clsx';
import { NumberField } from '@base-ui/react/number-field';
export function Root({ className, ...props }: NumberField.Root.Props) {
return ;
}
export function Group({ className, ...props }: NumberField.Group.Props) {
return ;
}
export function Decrement({ className, ...props }: NumberField.Decrement.Props) {
return (
);
}
export const Input = React.forwardRef(function Input(
{ className, ...props }: NumberField.Input.Props,
forwardedRef: React.ForwardedRef,
) {
return (
);
});
export function Increment({ className, ...props }: NumberField.Increment.Props) {
return (
);
}
```
```tsx
/* radio.tsx */
import * as React from 'react';
import clsx from 'clsx';
import { Radio } from '@base-ui/react/radio';
export function Root({ className, ...props }: Radio.Root.Props) {
return (
);
}
export function Indicator({ className, ...props }: Radio.Indicator.Props) {
return ;
}
```
```tsx
/* select.tsx */
import * as React from 'react';
import clsx from 'clsx';
import { Select } from '@base-ui/react/select';
export function Root(props: Select.Root.Props) {
return ;
}
export function Label({ className, ...props }: Select.Label.Props) {
return ;
}
export function Trigger({ className, ...props }: Select.Trigger.Props) {
return (
);
}
export function Value({ className, ...props }: Select.Value.Props) {
return ;
}
export function Icon(props: Select.Icon.Props) {
return ;
}
export function Portal(props: Select.Portal.Props) {
return ;
}
export function Positioner({ className, ...props }: Select.Positioner.Props) {
return ;
}
export function Popup({ className, ...props }: Select.Popup.Props) {
return (
);
}
export function ScrollUpArrow({ className, ...props }: Select.ScrollUpArrow.Props) {
return (
);
}
export function ScrollDownArrow({ className, ...props }: Select.ScrollDownArrow.Props) {
return (
);
}
export function List({ className, ...props }: Select.List.Props) {
return ;
}
export function Item({ className, ...props }: Select.Item.Props) {
return (
);
}
export function ItemIndicator({ className, ...props }: Select.ItemIndicator.Props) {
return ;
}
export function ItemText({ className, ...props }: Select.ItemText.Props) {
return ;
}
```
```tsx
/* slider.tsx */
import * as React from 'react';
import clsx from 'clsx';
import { Slider } from '@base-ui/react/slider';
export function Root({ className, ...props }: Slider.Root.Props) {
return ;
}
export function Value({ className, ...props }: Slider.Value.Props) {
return ;
}
export function Control({ className, ...props }: Slider.Control.Props) {
return ;
}
export function Track({ className, ...props }: Slider.Track.Props) {
return ;
}
export function Indicator({ className, ...props }: Slider.Indicator.Props) {
return ;
}
export function Thumb({ className, ...props }: Slider.Thumb.Props) {
return (
);
}
```
```tsx
/* switch.tsx */
import * as React from 'react';
import clsx from 'clsx';
import { Switch } from '@base-ui/react/switch';
export function Root({ className, ...props }: Switch.Root.Props) {
return (
);
}
export function Thumb({ className, ...props }: Switch.Thumb.Props) {
return (
);
}
```
```ts
/* stencil-hero.ts */
import { createForm } from './stencil-form';
import { connectToasts } from './stencil-toast';
export function mount(container: HTMLElement, themed = false) {
const elements = createForm(container, { themed });
const toasts = connectToasts(elements.provider, elements.toastViewport, themed);
elements.form.formSubmit = values => toasts.submit(values);
return () => {
toasts.destroy();
elements.destroy();
};
}
```
```ts
/* stencil-toast.ts */
import { createToastManager, type ToastObject } from 'finesoft-components/toast';
import type { Components } from 'finesoft-components';
const toastHTML = `
`;
const themedToastHTML = `
`;
export function connectToasts(provider: HTMLElement & Components.FsToastProvider, viewport: Element, themed = false) {
const manager = createToastManager();
const roots = new Map();
function update(event: CustomEvent) {
const toasts = event.detail;
for (const [id, root] of roots) {
if (!toasts.some(toast => toast.id === id)) {
root.remove();
roots.delete(id);
}
}
for (const toast of toasts) {
let root = roots.get(toast.id);
if (!root) {
const template = provider.ownerDocument.createElement('template');
template.innerHTML = themed ? themedToastHTML : toastHTML;
root = template.content.firstElementChild as HTMLElement & Components.FsToastRoot;
root.toast = toast;
root.querySelector('pre')!.textContent = JSON.stringify(toast.data, null, 2);
roots.set(toast.id, root);
viewport.append(root);
} else {
root.toast = toast;
}
}
}
provider.addEventListener('toastsChange', update as EventListener);
provider.toastManager = manager;
return {
submit: (data: unknown) => manager.add({ title: 'Form submitted', description: 'The form contains these values:', data: data as Record }),
destroy: () => provider.removeEventListener('toastsChange', update as EventListener),
};
}
```
Each runnable example below includes a FineSoft Stencil version. Open `stencil-form.ts` to see the actual ``, ``, `` and other Web Components tags used by all three examples. The native example uses `formSubmit`; TanStack Form uses its framework-independent core. React Hook Form retains only the React integration required by that library. Their visible event bindings exchange values through public properties and `CustomEvent.detail`; there are no React wrappers for the Stencil components. To run a native example, register `defineCustomElements()` from `finesoft-components/define-custom-elements`, then call its exported `mount(container)` function. Use its returned cleanup function on removal.
## Naming form controls
Form controls must have an accessible name in order to be recognized by assistive technologies. Use the label strategy below for each control type.
### Input controls
Use `` or a native `