avalonia-controls-input

---

name: avalonia-controls-input description: Use when working with Avalonia input controls: Button, ToggleButton, RadioButton, CheckBox, TextBox, ComboBox, Slider, Calendar, DatePicker, TimePicker, NumericUpDown, or VirtualKeyboard. Covers key properties, events, binding patterns, and common pitfalls for each control in Avalonia 12.

Avalonia Input Controls

Overview

Input controls capture user data or trigger actions. All support IsEnabled, IsVisible, and standard styling.

---

Button

Property	Type	Notes
Content	object	Any content, including XAML subtrees
Command	ICommand	Bound command; auto-manages IsEnabled
CommandParameter	object	Passed to command
IsDefault	bool	Triggers on Enter
IsCancel	bool	Triggers on Escape
ClickMode	ClickMode	Release (default), Press, Hover

Events: Click

Variants: RepeatButton (fires Click repeatedly while held), ToggleButton (stateful press)

<!-- Simple command button -->
<Button Content="Save" Command="{Binding SaveCommand}" IsDefault="True"/>

<!-- Button with icon + text -->
<Button Click="OnClick">
    <StackPanel Orientation="Horizontal" Spacing="8">
        <PathIcon Data="M17 3H5c-1.1 0-2 .9-2 2v14l7-3 7 3V5c0-1.1-.9-2-2-2z" Width="16" Height="16"/>
        <TextBlock Text="Save" VerticalAlignment="Center"/>
    </StackPanel>
</Button>

<!-- RepeatButton -->
<RepeatButton Content="+" Command="{Binding IncrementCommand}" Delay="400" Interval="100"/>

<!-- ToggleButton -->
<ToggleButton Content="Bold" IsChecked="{Binding IsBold}"/>

---

CheckBox

Property	Type	Notes
IsChecked	bool?	null = indeterminate
IsThreeState	bool	Enables null/indeterminate state
Content	object	Label displayed next to box

<!-- Basic binding -->
<CheckBox Content="Enable notifications" IsChecked="{Binding IsNotificationsEnabled}"/>

<!-- Three-state -->
<CheckBox Content="Select all" IsThreeState="True" IsChecked="{Binding AllSelected}"/>

// Handle indeterminate in ViewModel
private bool? _allSelected;
public bool? AllSelected
{
    get => _allSelected;
    set => SetProperty(ref _allSelected, value);
}

---

RadioButton

Property	Type	Notes
IsChecked	bool	TwoWay by default
GroupName	string	Groups buttons across panels
Content	object	Label

<!-- Grouped by GroupName -->
<StackPanel>
    <RadioButton Content="Small" GroupName="Size" IsChecked="{Binding IsSmall}"/>
    <RadioButton Content="Medium" GroupName="Size" IsChecked="{Binding IsMedium}"/>
    <RadioButton Content="Large" GroupName="Size" IsChecked="{Binding IsLarge}"/>
</StackPanel>

<!-- Grouped by parent panel (no GroupName needed) -->
<StackPanel>
    <RadioButton Content="Option A"/>
    <RadioButton Content="Option B"/>
</StackPanel>

Tip: For enum-based selection, bind each IsChecked to a converter comparing the enum value, or use ItemsControl with RadioButton items.

---

TextBox

Property	Type	Notes
Text	string	TwoWay by default — do not add Mode=TwoWay
Watermark	string	Placeholder text
MaxLength	int	0 = unlimited
AcceptsReturn	bool	Multiline input
TextWrapping	TextWrapping	NoWrap, Wrap, WrapWithOverflow
IsReadOnly	bool	Prevents editing
PasswordChar	char	Masks input (e.g. •)
SelectionStart	int	Caret/selection start
SelectionLength	int	Selection length
InnerLeftContent	object	Icon inside left edge
InnerRightContent	object	Icon inside right edge

Events: TextChanged, TextChanging, LostFocus, KeyDown

<!-- Basic -->
<TextBox Watermark="Enter name..." Text="{Binding Name}" MaxLength="100"/>

<!-- Multiline -->
<TextBox AcceptsReturn="True" TextWrapping="Wrap" Height="120" Text="{Binding Notes}"/>

<!-- Password -->
<TextBox PasswordChar="•" Watermark="Password" Text="{Binding Password}"/>

<!-- With inner icon -->
<TextBox Watermark="Search...">
    <TextBox.InnerLeftContent>
        <PathIcon Data="M15.5 14h-.79l-.28-.27A6.471..." Width="16" Height="16" Margin="4,0"/>
    </TextBox.InnerLeftContent>
</TextBox>

---

ComboBox

Property	Type	Notes
ItemsSource	IEnumerable	Bound collection
SelectedItem	object	TwoWay by default
SelectedIndex	int	Zero-based
SelectedValue	object	Used with SelectedValueBinding
IsEditable	bool	Allows text entry
PlaceholderText	string	Shown when nothing selected
MaxDropDownHeight	double	Limits dropdown height

<!-- Basic binding -->
<ComboBox ItemsSource="{Binding Options}"
          SelectedItem="{Binding SelectedOption}"
          PlaceholderText="Select..."/>

<!-- Custom item template -->
<ComboBox ItemsSource="{Binding Countries}" SelectedItem="{Binding SelectedCountry}">
    <ComboBox.ItemTemplate>
        <DataTemplate x:DataType="vm:CountryVm">
            <StackPanel Orientation="Horizontal" Spacing="8">
                <Image Source="{Binding FlagUri}" Width="20" Height="14"/>
                <TextBlock Text="{Binding Name}"/>
            </StackPanel>
        </DataTemplate>
    </ComboBox.ItemTemplate>
</ComboBox>

<!-- Editable ComboBox -->
<ComboBox IsEditable="True" ItemsSource="{Binding Suggestions}" Text="{Binding InputText}"/>

---

Slider

Property	Type	Notes
Minimum	double	Default: 0
Maximum	double	Default: 100
Value	double	TwoWay by default
TickFrequency	double	Interval between ticks
IsSnapToTickEnabled	bool	Snaps value to tick marks
Orientation	Orientation	Horizontal (default), Vertical
IsDirectionReversed	bool	Inverts direction
TickPlacement	TickPlacement	None, TopLeft, BottomRight, Outside

<!-- Horizontal volume slider -->
<Slider Minimum="0" Maximum="100" Value="{Binding Volume}"
        TickFrequency="10" IsSnapToTickEnabled="True" TickPlacement="BottomRight"/>

<!-- Vertical slider -->
<Slider Orientation="Vertical" Minimum="0" Maximum="1"
        Value="{Binding Opacity}" Height="200"/>

---

NumericUpDown

Property	Type	Notes
Value	decimal?	TwoWay by default
Minimum	decimal?	Lower bound
Maximum	decimal?	Upper bound
Increment	decimal	Step per click
FormatString	string	e.g. "F2", "N0", "C2"
AllowSpin	bool	Show up/down buttons
ShowButtonSpinner	bool	Toggle spinner visibility
NumberFormat	NumberFormatInfo	Culture-specific formatting

<!-- Integer quantity -->
<NumericUpDown Value="{Binding Quantity}" Minimum="1" Maximum="999" Increment="1" FormatString="N0"/>

<!-- Decimal with currency -->
<NumericUpDown Value="{Binding Price}" Minimum="0" Increment="0.01" FormatString="C2"/>

<!-- No spinner buttons -->
<NumericUpDown Value="{Binding Amount}" AllowSpin="False"/>

---

Calendar

Property	Type	Notes
SelectedDate	DateTime?	Selected date
DisplayMode	CalendarMode	Month, Year, Decade
DisplayDate	DateTime	Currently displayed month
BlackoutDates	CalendarBlackoutDatesCollection	Disabled dates
IsTodayHighlighted	bool	Highlights today
SelectionMode	CalendarSelectionMode	SingleDate, SingleRange, MultipleRange, None

<Calendar SelectedDate="{Binding SelectedDate}"
          DisplayMode="Month"
          IsTodayHighlighted="True"/>

<!-- With blackout dates in code-behind -->

calendar.BlackoutDates.Add(new CalendarDateRange(DateTime.Today.AddDays(1), DateTime.Today.AddDays(7)));

---

DatePicker

Property	Type	Notes
SelectedDate	DateTimeOffset?	Note: not DateTime
DisplayDateStart	DateTimeOffset?	Earliest selectable
DisplayDateEnd	DateTimeOffset?	Latest selectable
Watermark	string	Placeholder
DayFormat	string	Day display format
MonthFormat	string	Month display format
YearFormat	string	Year display format

<DatePicker SelectedDate="{Binding BirthDate}" Watermark="Select date"/>

<!-- Restrict range -->
<DatePicker SelectedDate="{Binding AppointmentDate}"
            DisplayDateStart="{Binding TodayOffset}"
            DisplayDateEnd="{Binding MaxDateOffset}"/>

// Convert DateTimeOffset? to DateTime for use
DateTime? date = picker.SelectedDate?.DateTime;

---

TimePicker

Property	Type	Notes
SelectedTime	TimeSpan?	Selected time value
ClockIdentifier	string	"12HourClock" or "24HourClock"
MinuteIncrement	int	Snap interval (1–59)

<TimePicker SelectedTime="{Binding MeetingTime}" ClockIdentifier="24HourClock"/>

<TimePicker SelectedTime="{Binding AlarmTime}" ClockIdentifier="12HourClock" MinuteIncrement="15"/>

---

Common Mistakes

Mistake	Fix
TextBox Text="{Binding X, Mode=TwoWay}"	Remove Mode=TwoWay — it's the default
ComboBox with value types, SelectedItem not working	Use SelectedIndex or ensure proper equality; value types match by value but boxed objects may not
All RadioButtons in same panel auto-group	Use GroupName to separate groups across panels or force cross-panel grouping
DatePicker.SelectedDate typed as DateTime	It's DateTimeOffset? — convert with .DateTime
NumericUpDown.Value typed as double	It's decimal? — use decimal in ViewModel
TextBox binding not updating on every keystroke	Default updates on LostFocus; use UpdateSourceTrigger=PropertyChanged if needed
PasswordChar with compiled bindings	No issue, but Text binding exposes password in ViewModel — consider SecureString patterns