Enciphered.Blazor.UIComponents/docs/components/form-inputs.md

Form Inputs

All input components extend a shared InputBase<T> class that provides consistent styling, htmx validation integration, and parameter unification. When placed inside an HtmxForm with a FormField, inputs automatically attach hx-post, hx-trigger="blur", and hx-target attributes for real-time per-field validation.

---

TextInput

A standard text input for strings. Supports all HTML input types (text, email, password, search, etc.).

<FormField Label="Full Name" For="name">
    <TextInput Id="name" Name="name" Placeholder="Jane Doe" />
</FormField>

<FormField Label="Email" For="email">
    <TextInput Id="email" Name="email" Type="email" Placeholder="jane@example.com" />
</FormField>

<FormField Label="Password" For="password">
    <TextInput Id="password" Name="password" Type="password" Placeholder="••••••••" />
</FormField>

Parameters

Parameter	Type	Default	Description
Type	string	"text"	HTML input type
Id	string?	—	Input element ID
Name	string?	—	Form field name (submitted to the server)
Value	string?	—	Current value
Placeholder	string?	—	Placeholder text
Disabled	bool	false	Disables the input
ReadOnly	bool	false	Makes the input read-only
Class	string?	—	Additional CSS classes

---

NumberInput

A numeric input with built-in increment/decrement stepper buttons. Hides the browser's native spinner.

<FormField Label="Age" For="age">
    <NumberInput Id="age" Name="age" Placeholder="25" Min="0" Max="150" />
</FormField>

<FormField Label="Quantity" For="quantity">
    <NumberInput Id="quantity" Name="quantity" Value="1" Min="1" Max="99" Step="1" />
</FormField>

Parameters

Parameter	Type	Default	Description
Min	string?	—	Minimum allowed value
Max	string?	—	Maximum allowed value
Step	string?	—	Step increment
Value	double?	—	Current numeric value

Inherits all parameters from InputBase<double?> (Id, Name, Placeholder, Disabled, ReadOnly, Class).

The stepper buttons are disabled when the value reaches Min or Max. They are hidden when Disabled or ReadOnly is true.

---

DateInput

A date picker that combines a hidden <input type="date"> with a popover calendar. Users select dates through the calendar UI — the native date picker chrome is hidden.

<FormField Label="Birth Date" For="birthdate">
    <DateInput Id="birthdate" Name="birthdate" Placeholder="Select your birth date" />
</FormField>

How it works

1. A hidden <input type="date"> holds the actual form value in yyyy-MM-dd format
2. A styled button trigger shows the selected date (or placeholder)
3. Clicking the trigger opens a Popover containing a Calendar component
4. Selecting a day updates the hidden input and closes the popover

Parameters

Parameter	Type	Default	Description
Value	DateOnly?	—	Currently selected date
Min	string?	—	Minimum date
Max	string?	—	Maximum date
Placeholder	string?	"Select date"	Trigger button placeholder

Inherits all parameters from InputBase<DateOnly?>.

---

TimeInput

A time picker that combines a hidden <input type="time"> with a popover time picker. Features scrollable hour/minute columns and AM/PM toggle.

<FormField Label="Preferred Time" For="preferredtime">
    <TimeInput Id="preferredtime" Name="preferredtime" />
</FormField>

Parameters

Parameter	Type	Default	Description
Value	TimeOnly?	—	Currently selected time
Step	string?	—	Minute step interval
Use12Hour	bool	true	12-hour format with AM/PM
Placeholder	string?	"Select time"	Trigger button placeholder

Inherits all parameters from InputBase<TimeOnly?>.

---

DateTimeInput

Combines a date picker and time picker side by side for selecting both date and time. Internally manages a hidden <input type="datetime-local"> plus two helper hidden inputs for the date and time parts.

<FormField Label="Appointment" For="appointment">
    <DateTimeInput Id="appointment" Name="appointment" />
</FormField>

How it works

1. A hidden <input type="datetime-local"> holds the combined value in yyyy-MM-ddTHH:mm format
2. Two helper hidden inputs hold the date-part and time-part separately
3. Two popover triggers (calendar + time picker) are displayed side by side
4. The forms.js module automatically combines the date-part and time-part values into the main hidden input

Parameters

Parameter	Type	Default	Description
Value	DateTime?	—	Currently selected date and time
Min	string?	—	Minimum datetime
Max	string?	—	Maximum datetime
Step	string?	—	Minute step interval
Placeholder	string?	"Select date"	Date trigger placeholder

Inherits all parameters from InputBase<DateTime?>.

---

FormField

Wraps an input with a label, description, and error placeholder. The error element is used by htmx to display server-side validation messages.

<FormField Label="Email" For="email" Description="We'll never share your email.">
    <TextInput Id="email" Name="email" Type="email" />
</FormField>

Parameters

Parameter	Type	Default	Description
Label	string?	—	Label text rendered as <label>
For	string?	—	Links the label to the input, and identifies the field for validation errors
Description	string?	—	Helper text below the input
Error	string?	—	Pre-set error message (for server-rendered errors)
Class	string?	—	Additional CSS classes on the wrapper
LabelClass	string?	—	Additional CSS classes on the label

How validation errors are displayed

FormField renders a <p data-field-error="fieldname"> element. When htmx receives a validation response, it swaps this element with the server's HTML fragment (which includes or hides the error message). This is the core mechanism for per-field validation.

---

InputBase

All input components inherit from InputBase<TValue>, which provides:

• Common parameters: Id, Name, Value, Placeholder, Disabled, ReadOnly, Class
• Computed CSS: A consistent input style using Tailwind classes
• htmx auto-wiring: When ValidationEndpoint and FieldName cascading values are present (provided by HtmxForm and FormField), the input automatically gets:
  • hx-post pointing to the validation endpoint
  • hx-trigger="blur" for on-blur validation
  • hx-target="next [data-field-error]" to update the error element
  • hx-swap="outerHTML" for full element replacement
  • hx-include="this" to send only this input's value
  • hx-vals='{"_field": "fieldname"}' to identify which field is being validated