syncfusion-blazor-toolkit-inputs

# Syncfusion Blazor Toolkit - Input Components > ⚙️ **Render mode:** `SfTextBox`, `SfTextArea`, `SfNumericTextBox<T>`, `SfCheckBox<T>`, `SfRadioButton<T>`, `SfSwitch<T>` work in all modes. **`SfUploader`** and **`InputFile` are NOT usable in Static SSR** — they require interactive render mode (Server, WebAssembly, or Auto @ .NET 8+). Read `AGENTS.md` before wiring file uploads. ## Core Rules 1. **Use `@bind-Value` for two-way binding**; use `ValueChanged` only when you need to inspect without binding. Never both. 2. **`TValue` and `TChecked` generic params must match the bound C# type.** `SfNumericTextBox<T>` requires `T : struct, IFormattable` — `T=string` compiles and crashes at runtime. 3. **`SfUploader` and `<InputFile>` are NOT usable in Static SSR** — the file-system path / JavaScript interop is unavailable. 4. **`SfUploader` requires a `SaveUrl`** (an HTTP endpoint); never point it at a static path on disk. 5. **`SfUploader` has a SignalR message-size limit (Server mode)** — call `OpenReadStream(maxAllowedSize)` to lift it for large uploads. 6. **`SfCheckBox<T>`**, **`SfRadioButton<T>`**, and **`SfSwitch<T>` use `TChecked` not `T`** in the generic parameter — be careful when copy-pasting between CheckBox and Switch. 7. **`SfNumericTextBox` accepts `Format` as a string** — `Format="C2"`, `Format="P"`, `Format="N0"`. The value is `CultureInfo.CurrentCulture` aware. **For currency, prefer a literal culture-locked pattern (e.g. `Format="$#,##0.00"`) to avoid locale-dependent UX.** 8. **Component parameter required** — use `[EditorRequired]` attribute on your `[Parameter]` declaration (compile-time check for component authors). 9. **Form-field required** — use `[Required]` (and other `DataAnnotations` attributes) on a model property, then include `<DataAnnotationsValidator />` inside `<EditForm>`. Without it, `[Required]` is silently ignored. 10. **`ID` and `Name` come from `HtmlAttributes`** if not explicitly supplied — don't rely on them being filled in. 11. **`ValueChange` fires before binding commits.** Use `@bind-Value:after` for post-commit validation or side effects. ## Don'ts | Anti-pattern | Symptom | Fix | |---|---|---| | `SfCheckBox TChecked="string"` | Compile succeeds; runtime throws "Cannot convert null to bool" on first render | Use `TChecked="bool"` (or `int?` for 3-state) | | `SfUploader` `AutoUpload="true"` on a static URL path | 404 / 405 from web server; upload "completes" but file is lost in client browser | Always POST to a controller endpoint that handles `IFormFile` and returns 200 | | `<SfUploader>` / `<InputFile>` in a Static SSR page | Component never receives a file (`IBrowserFile` is null); prerender is always empty | Move to a `Server | WebAssembly | Auto` page or `@rendermode InteractiveServer`-only page | | `SfNumericTextBox T="decimal" Format="N2"` for currency | Field shows `1,234.56` for en-US but `1.234,56` for de-DE — inconsistent UX | Use `Format="C2"` so the currency formatter takes culture into account; **or lock the format** (`Format="$#,##0.00"`) for culture-stable display | | `<SfNumericTextBox @bind-Disabled="…" />` | Compile error or ignored — `Disabled` is a one-way attribute | Use `<SfNumericTextBox Disabled="@_busy" />` and toggle `_busy` manually | | Two `SfNumericTextBox<T>` of different `T` in one `EditForm` row | Validation can bind to the wrong field; `@bind-Value` resolves to the first match | Set explicit `TValue` per input or split rows | | Missing `<DataAnnotationsValidator />` in `<EditForm>` | All `[Required]`/`[StringLength]` rules silently ignored; form submits invalid data | Always include `<DataAnnotationsValidator />` as the first child of `<EditForm>` | | Stripping `class="e-input"` from the rendered `<input>` | Numeric arrows / clear-button vanish; keyboard users lose step controls | Scope styling to parent (`<div>` / `<label>`) instead of the inner `<input>` | | Binding `Value="@_text"` *and* `@bind-Value` | Property is set twice; one wins silently; `StateHasChanged` order is undefined | Pick exactly one | | Setting `Min`/`Max` on `SfDatePicker` (not `SfNumericTextBox`) | That property doesn't exist on `SfDatePicker`; silent no-op | Use `Min`/`Max` on `SfDatePicker`, `Min`/`Max`/`Step` on `SfNumericTextBox` | ## Anti-Pattern Workflows ### Workflow 1 — Agent lifecycle: `OnInitialized` reads `IBrowserFile` **Bad:** ```razor @code { private IBrowserFile? _file; protected override void OnInitialized() { _file = HttpContext.GetFile(); } } ``` **Why it fails:** `IBrowserFile` only exists inside an `InputFileChangeEventArgs` from `<InputFile OnChange>`. Reading "out of band" returns null and produces blank components. **Correct:** ```razor <InputFile OnChange="@LoadFile" accept=".pdf,.jpg,.png" /> @code { private IBrowserFile? _file; private async Task LoadFile(InputFileChangeEventArgs e) { _file = e.File; await using var stream = _file.OpenReadStream(maxAllowedSize: 10 * 1024 * 1024); // process stream safely } } ``` ### Workflow 2 — Agent sets `TChecked` to `string` because the doc looked similar **Bad:** ```razor <SfCheckBox TChecked="string" @bind-Checked="@_checked" Label="Agree" /> @code { private string _checked; /* user checks => binding expects bool */ } ``` **Correct:** ```razor <SfCheckBox TChecked="bool" @bind-Checked="@_agreed" Label="Agree to terms" /> @code { private bool _agreed; } ``` ### Workflow 3 — Agent omits `DataAnnotationsValidator` because the model has `[Required]` **Bad:** ```razor <EditForm Model="user" OnValidSubmit="SaveAsync"> <InputText @bind-Value="user.Name" /> <button type="submit">Save</button> </EditForm> ``` **Why it fails:** `[Required]` is metadata; `<EditForm>` only enforces it when `<DataAnnotationsValidator />` is present. **Correct:** ```razor <EditForm Model="user" OnValidSubmit="SaveAsync"> <DataAnnotationsValidator /> <ValidationSummary /> <InputText @bind-Value="user.Name" /> <button type="submit">Save</button> </EditForm> ``` ### Workflow 4 — Agent tries to disable just one field inside an `EditForm` **Bad:** model has `bool _busy`; agent uses `Disabled="@_busy"` on **every** input — now the form is fully inert, including the submit button. The user cannot resubmit if there's a server-side error. **Correct:** ```razor <button type="submit" disabled="@_busy">@(_busy ? "Saving…" : "Save")</button> @code { private bool _busy; private async Task SaveAsync() { _busy = true; try { await UserService.SaveAsync(user); } catch { /* keep `_busy=false` so user can retry */ _busy = false; throw; } finally { _busy = false; } } } ``` Inputs remain enabled; the Submit button reflects state. ### Workflow 5 — Agent wants to set default culture for `Format="C2"` currency **Bad:** `Format="C2"` displays "£123.45" for `CultureInfo("en-GB")` but "$123.45" for `en-US` — depends on the user's runtime culture. This is rarely a feature; it's more often a bug. **Correct:** wrap the entire `<CascadingValue Value="@culture">` around the form, set `CultureInfo.DefaultThreadCurrentCulture = …` once in `Program.cs`, or hard-code the culture in `Format`: ```razor <SfNumericTextBox TValue="decimal" Format="$#,##0.00" Min="0" Max="10000" @bind-Value="@price" /> <!-- Always $ regardless of browser locale. --> ``` ## Minimal Example ```razor @using Syncfusion.Blazor.Toolkit.Inputs @using System.ComponentModel.DataAnnotations <EditForm Model="@formModel" OnValidSubmit="@Save"> <DataAnnotationsValidator /> <ValidationSummary /> <label>Email:</label> <SfTextBox @bind-Value="@formModel.Email" /> <ValidationMessage For="@(() => formModel.Email)" /> <button type="submit">Save</button> </EditForm> @code { private LoginModel formModel = new(); private void Save() { /* handle submit */ } public class LoginModel { [Required, EmailAddress] public string Email { get; set; } = ""; } } ``` --- ## Documentation and Navigation Guide | Component family | Read | |---|---| | Setup, CSS imports, theming | [references/getting-started-inputs.md](references/getting-started-inputs.md) | | `SfTextBox`, `SfTextArea`, floating labels, focus/blur, validation states | [references/textbox-textarea.md](references/textbox-textarea.md) | | `SfNumericTextBox<T>`, currency, percentage, Min/Max/Step, decimals, spin buttons | [references/numeric-currency.md](references/numeric-currency.md) | | `SfUploader` (auto upload, multi-file, size/type validation, progress, drag-drop, errors) | [references/uploader.md](references/uploader.md) | | `SfCheckBox<T>`, `SfRadioButton<T>`, `SfSwitch<T>`, grouped/conditional patterns | [references/checkbox-radio-switch.md](references/checkbox-radio-switch.md) | | WCAG / keyboard / ARIA / labels / error announcement | [references/input-accessibility.md](references/input-accessibility.md) | --- ## Next Steps 1. **Setup:** [references/getting-started-inputs.md](references/getting-started-inputs.md) 2. **Component you're using:** one of the per-component references above 3. **Accessibility audit:** [references/input-accessibility.md](references/input-accessibility.md) **Demo:** https://blazor.syncfusion.com/demos/toolkit/inputs