Skip to content

form-controls.md

Latest commit

 

History

History
361 lines (247 loc) · 10.7 KB

form-controls.md

File metadata and controls

361 lines (247 loc) · 10.7 KB

Form Controls & EditForm Integration

Part of the igniteui-blazor-components skill hub. For project setup and module registration - see setup.md.

Contents

Overview

This reference gives high-level guidance on form controls, their key features, and common API members. For detailed documentation, call get_doc from igniteui-cli; use search_api and get_api_reference for Blazor API details.

Input

Docs: Input

// Program.cs
builder.Services.AddIgniteUIBlazor(typeof(IgbInputModule));
<IgbInput @bind-Value="UserName" Label="Username" Placeholder="e.g. John Doe">
    <span slot="prefix">User</span>
</IgbInput>

@code {
    string UserName { get; set; } = "";
}

Key attributes: Label, Placeholder, DisplayType (InputType.Text / Email / Password / Tel / Number), Required, Disabled, Readonly, MinLength, MaxLength.

Slots: prefix, suffix, helper-text.

Events: IgbInput (fires while typing), Change (fires on commit/blur).

Combo Box

Docs: Combo Box

builder.Services.AddIgniteUIBlazor(typeof(IgbComboModule));
<IgbCombo T="City"
          Data="Cities"
          ValueKey="Id"
          DisplayKey="Name"
          Label="Select Cities"
          Placeholder="Pick a city" />

@code {
    private List<City> Cities = SampleData.Cities;

    record City(string Id, string Name, string Country);
}

Key attributes: Data, ValueKey (required for complex objects), DisplayKey, T (type parameter - must match ValueKey property type or "object" if no ValueKey), Label, Placeholder, SingleSelect (for single-selection mode), Disabled, Required.

Events: Opening, Opened, Closing, Closed, SelectionChanging.

AGENT INSTRUCTION: IgbCombo does not work inside a standard HTML <form>. Use <EditForm> with @bind-Value instead.

Select

Docs: Select

builder.Services.AddIgniteUIBlazor(typeof(IgbSelectModule));
<IgbSelect Label="Fruit" Placeholder="Choose a fruit">
    <IgbSelectItem Value="apple">Apple</IgbSelectItem>
    <IgbSelectItem Value="orange">Orange</IgbSelectItem>
    <IgbSelectItem Value="banana">Banana</IgbSelectItem>
</IgbSelect>

For grouped options use IgbSelectHeader and IgbSelectGroup. Key attributes on IgbSelect: Label, Placeholder, Outlined, Disabled, Required, Name. On IgbSelectItem: Value, Selected, Disabled.

Slots on IgbSelect: header, footer, helper-text, prefix, suffix, toggle-icon.

Date Picker

Docs: Date Picker

builder.Services.AddIgniteUIBlazor(typeof(IgbDatePickerModule));
<IgbDatePicker @ref="Picker" Value="@SelectedDate" />

@code {
    public IgbDatePicker Picker { get; set; }
    public DateTime SelectedDate { get; set; } = DateTime.Today;
}

Key attributes: Value (DateTime), Min, Max, InputFormat, DisplayFormat, Locale, Mode (PickerMode.Dropdown / PickerMode.Dialog), ShowWeekNumbers, WeekStart, Disabled, Required.

Slots: calendar, clear, prefix, suffix, actions (custom footer buttons).

Methods: StepUp(DatePart), StepDown(DatePart), Clear(), Show(), Hide(), Toggle().

Date Range Picker

Docs: Date Range Picker

builder.Services.AddIgniteUIBlazor(typeof(IgbDateRangePickerModule));
<IgbDateRangePicker @ref="RangePicker" />

@code {
    public IgbDateRangePicker RangePicker { get; set; }
}

Returns a start and end DateTime. Key attributes: Min, Max, InputFormat, Locale, Mode.

Calendar

Docs: Calendar

builder.Services.AddIgniteUIBlazor(typeof(IgbCalendarModule));
<IgbCalendar />

Use Calendar when the UI needs an always-visible date picker rather than an input/dropdown picker. For multiple selection, range selection, special dates, disabled dates, visible months, week numbers, and localization, use the exact property names from the calendar MCP doc before writing markup.

Date Time Input

Docs: Date Time Input

builder.Services.AddIgniteUIBlazor(typeof(IgbDateTimeInputModule));
<IgbDateTimeInput @bind-Value="SelectedDateTime"
                  InputFormat="MM/dd/yyyy HH:mm"
                  SpinLoop="true" />

@code {
    public DateTime? SelectedDateTime { get; set; } = DateTime.Now;
}

Key attributes: Value (DateTime?), InputFormat, DisplayFormat, Min, Max, MinutesStep, SpinLoop.

Methods: StepUp(), StepDown(), Clear().

Mask Input

Docs: Mask Input

builder.Services.AddIgniteUIBlazor(typeof(IgbMaskInputModule));
<IgbMaskInput Mask="(000) 000-0000"
              Label="Phone Number"
              Placeholder="(555) 123-4567" />

Key attributes: Mask (pattern string: 0 = digit, L = letter, A = alphanumeric), Placeholder, Prompt (fill character, default _), ValueMode (raw or withFormatting).

Checkbox

Docs: Checkbox

builder.Services.AddIgniteUIBlazor(typeof(IgbCheckboxModule));
<IgbCheckbox @bind-Checked="IsSubscribed">Subscribe to newsletter</IgbCheckbox>

@code {
    bool IsSubscribed { get; set; }
}

Key attributes: Checked, Indeterminate, Disabled, Required, Invalid, LabelPosition (ToggleLabelPosition.After / Before), Name, Value.

CSS parts: base, control, indicator, label.

Radio / Radio Group

Docs: Radio & Radio Group

builder.Services.AddIgniteUIBlazor(typeof(IgbRadioModule), typeof(IgbRadioGroupModule));
<IgbRadioGroup Alignment="@ContentOrientation.Vertical" Name="plan">
    <IgbRadio Value="basic">Basic</IgbRadio>
    <IgbRadio Value="pro">Pro</IgbRadio>
    <IgbRadio Value="enterprise">Enterprise</IgbRadio>
</IgbRadioGroup>

Key attributes on IgbRadioGroup: Alignment (ContentOrientation.Horizontal / ContentOrientation.Vertical), Name. On IgbRadio: Value, Checked, Disabled, Invalid, LabelPosition.

Switch

Docs: Switch

builder.Services.AddIgniteUIBlazor(typeof(IgbSwitchModule));
<IgbSwitch @bind-Checked="IsDarkMode">Dark Mode</IgbSwitch>

@code {
    bool IsDarkMode { get; set; }
}

Key attributes: Checked, Disabled, Required, LabelPosition.

Slider / Range Slider

Docs: Slider & Range Slider

builder.Services.AddIgniteUIBlazor(typeof(IgbSliderModule), typeof(IgbRangeSliderModule));
<!-- Single value -->
<IgbSlider Value="40" Min="0" Max="100" Step="5" Change="OnSliderChange" />

<!-- Range -->
<IgbRangeSlider Lower="20" Upper="70" Change="OnRangeChange" />

@code {
    void OnSliderChange(IgbNumberEventArgs e) => Console.WriteLine(e.Detail);
    void OnRangeChange(IgbRangeSliderValueEventArgs e)
    {
        var lower = e.Detail.Lower;
        var upper = e.Detail.Upper;
    }
}

Key attributes on IgbSlider: Value, Min, Max, Step, Disabled, HideTooltip. On IgbRangeSlider: Lower, Upper, Min, Max, Step.

Events (both): IgbInput (fires while dragging), Change (fires on commit).

Rating

Docs: Rating

builder.Services.AddIgniteUIBlazor(typeof(IgbRatingModule));
<IgbRating @bind-Value="StarRating" Max="5" />

@code {
    double StarRating { get; set; } = 3;
}

Key attributes: Value, Max, Step (for half-star: 0.5), Disabled, Readonly, Label, ValueFormat.

Events: Change, Hover.

Form & Binding Notes

AGENT INSTRUCTION: Do not assume one universal form integration pattern. Several Ignite UI Blazor components such as IgbCombo and IgbRadio do not work with a standard HTML <form> element. Use the MCP doc for the exact component, bind values explicitly, and only use a form pattern shown by the current docs.

<IgbInput @bind-Value="Model.Name" Label="Name" Required="true" />
<IgbCheckbox @bind-Checked="Model.Agreed">I agree to the terms</IgbCheckbox>
<IgbSelect @bind-Value="Model.Country" Label="Country" Name="country">
    <IgbSelectItem Value="us">United States</IgbSelectItem>
    <IgbSelectItem Value="uk">United Kingdom</IgbSelectItem>
</IgbSelect>

@code {
    public class FormModel
    {
        [Required] public string Name { get; set; } = "";
        public bool Agreed { get; set; }
        public string Country { get; set; } = "";
    }

    FormModel Model = new();

    void Save() { /* validate and persist Model using the pattern required by your app */ }
}

Key Rules

  1. Do not wrap Ignite UI inputs in a standard HTML <form> unless the component doc shows that pattern. Form behavior differs by component.
  2. Register every module you use in Program.cs using the typeof(Igb{Name}Module) pattern.
  3. IgbCombo requires the T type parameter - set it to the type of your ValueKey property, or "object" if there is no ValueKey.
  4. Use @bind-Value / @bind-Checked for two-way data binding in Blazor.
  5. IgbSlider and IgbRangeSlider have separate modules - register both if you use range sliders.