193 lines
7.0 KiB
Markdown
193 lines
7.0 KiB
Markdown
# 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.).
|
|
|
|
```razor
|
|
<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.
|
|
|
|
```razor
|
|
<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.
|
|
|
|
```razor
|
|
<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.
|
|
|
|
```razor
|
|
<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.
|
|
|
|
```razor
|
|
<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.
|
|
|
|
```razor
|
|
<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
|