components / 35

marked field

validation should explain itself. the same boundary carries rest, focus, dirty, touched, and invalid without changing the native form contract.

shadcnnpx shadcn@latest add berkantay/cheez/marked-field

live

the field remembers the interaction

blur or submit to validate

ink

size

character

controlled valueempty

<MarkedField validationMode="onBlur" tone="orange" size="medium">
  <MarkedFieldLabel required>email</MarkedFieldLabel>
  <MarkedFieldControl
    type="email"
    required
    value={email}
    onValueChange={setEmail}
  />
  <MarkedFieldDescription>only used for receipts</MarkedFieldDescription>
  <MarkedFieldError match="valueMissing">email is required</MarkedFieldError>
  <MarkedFieldError match="typeMismatch">use a complete address</MarkedFieldError>
</MarkedField>

matching

one cause, one useful sentence

native and custom validity

valueMissing

project name

name the project.

typeMismatch

website

include https://

custom

handle

timing

choose when feedback becomes useful

not every field should interrupt

on submitquiet until asked

best when the form can be completed without immediate correction.

on blurafter the thought

validate when someone leaves the control, not while they are typing.

on changecontinuous signal

use debounce for remote checks and expensive custom rules.

reference

api

Base UI validity, Cheez explanation

part	prop	type	default	purpose
Root	`validationMode`	`"onSubmit" \| "onBlur" \| "onChange"`	`"onSubmit"`	when validation begins
Root	`validationDebounceTime`	`number`	`0`	delay on-change validation
Root	`validate`	`function`	`—`	custom sync or async validation
Root	`invalid`	`boolean`	`—`	external controlled validity
Root	`dirty / touched`	`boolean`	`—`	external interaction state
Root	`actionsRef`	`RefObject`	`—`	imperative validate action
Root	`tone`	`MarkedFieldTone`	`"orange"`	resting boundary ink
Root	`size`	`small \| medium \| large`	`"medium"`	control density
Control	`onValueChange`	`function`	`—`	controlled string value
Control	`native constraints`	`input props`	`—`	required, type, minLength…
Error	`match`	`boolean \| keyof ValidityState`	`—`	show a specific error
Label	`nativeLabel`	`boolean`	`true`	association behavior
Validity	`children`	`render function`	`—`	inspect the full validity object

behavior notes

labels and descriptions associate automatically with the control
native constraints and custom validation share one validity model
errors can target valueMissing, typeMismatch, rangeOverflow, or any ValidityState key
custom validation may return a string, string array, Promise, or null
dirty means changed; touched means the control has been visited
association, validation timing, and error transitions come from Base UI
no Framer Motion is shipped