Avalonia Controls Navigation

Avalonia Navigation Controls

Overview

Navigation controls let users move between views or trigger application commands. All menu controls support Command binding and keyboard shortcuts via InputGesture.

---

TabControl

Displays content in tabbed panels. Tabs can be static (inline TabItem) or dynamic (bound ItemsSource).

| Property | Type | Notes | |---|---|---| | SelectedIndex | int | TwoWay | | SelectedItem | object | TwoWay | | TabStripPlacement | Dock | Top (default), Bottom, Left, Right | | ItemsSource | IEnumerable | For dynamic tabs | | ItemTemplate | DataTemplate | Header template for dynamic tabs | | ContentTemplate | DataTemplate | Body template for dynamic tabs |

TabItem properties:

| Property | Notes | |---|---| | Header | Tab label (string or XAML) | | Content | Tab body | | IsEnabled | Disables individual tab | | IsSelected | Set programmatically |

Dynamic tabs (ViewModel-driven):

public class TabVm
{
    public string Title { get; set; } = "";
    public object? Content { get; set; }
}

---

Menu

Top-level application menu bar. Contains MenuItem hierarchy.

| Property | Notes | |---|---| | Header | Text label; prefix with _ for access key | | Command | Bound command | | CommandParameter | Passed to command | | Icon | Left-side icon (usually Image or PathIcon) | | InputGesture | Keyboard shortcut (display only for top-level; functional for items) | | Items | Sub-menu items | | IsEnabled | Disables item |

---

ContextMenu

Attached to any control. Shown on right-click.

| Property | Notes | |---|---| | Items | MenuItem list | | IsOpen | Programmatic open/close |

> DataContext pitfall: ContextMenu is not in the visual tree of its host control. Its DataContext is the control's DataContext by default, but ancestor binding ($parent[Window]) must be used to reach the Window's ViewModel. Alternatively, set DataContext explicitly in code.

// Set ContextMenu DataContext explicitly in code-behind
myControl.ContextMenu!.DataContext = this.DataContext;

---

NativeMenu

Platform-native menus. Used for macOS app menus and TrayIcon menus.

---

TrayIcon

System tray icon for desktop apps. Desktop lifetime only.

In App.axaml:

// In App.axaml.cs — wire DataContext for TrayIcon commands
public override void OnFrameworkInitializationCompleted()
{
    if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
    {
        var vm = new MainWindowViewModel();
        desktop.MainWindow = new MainWindow { DataContext = vm };

        // TrayIcon DataContext
        if (TrayIcon.GetIcons(this) is { } icons)
            foreach (var icon in icons)
                icon.DataContext = vm;  // or a dedicated TrayIconVm
    }
    base.OnFrameworkInitializationCompleted();
}

Icon formats: .ico recommended for Windows; .png works on Linux/macOS.

---

Common Mistakes

| Mistake | Fix | |---|---| | Access key not working in MenuItem.Header | Use _ prefix: Header="_File" (Alt+F). Without _, no access key is registered | | ContextMenu command binding fails | ContextMenu is not in visual tree; use $parent[Window].DataContext.Cmd or set DataContext in code | | TrayIcon crashes on non-desktop lifetime | Guard: if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime) before using TrayIcon | | TabControl dynamic tabs show blank content | Provide both ItemTemplate (header) and ContentTemplate (body), or use ContentControl in body template | | MenuItem.InputGesture not firing | InputGesture on MenuItem only shows the hint; actual shortcut requires KeyBinding at the window level | | Dynamic submenu bound Items not showing | Use Items="{Binding ...}" with an ItemTemplate on the parent MenuItem, not ItemsSource |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: linuxdevel
• Source: linuxdevel/Avalonia-skills
• License: MIT

Install and usage instructions live in the source repository linked above.