---

name: mosaic-controls description: "Overview of all Mosaic UI for WPF controls. Use when: implementing a control, looking up properties/events, asking what controls exist, choosing the right control for a UI requirement." argument-hint: "Optional: name of a specific control to focus on (e.g. 'ToggleSwitch', 'AutoCompleteBox')"

Mosaic UI for WPF — Control Overview

Mosaic UI for WPF (Mosaic.UI.Wpf) is a lookless, theme-aware WPF control library. Controls are consumed via the canonical XML namespace:

xmlns:mosaic="http://schemas.apexgate.net/wpf/mosaic-ui"

or the CLR form:

xmlns:mosaic="clr-namespace:Mosaic.UI.Wpf.Controls;assembly=Mosaic.UI.Wpf"

The VT52Terminal control requires the sub-namespace:

xmlns:vt52="clr-namespace:Mosaic.UI.Wpf.Controls.VT52Terminal;assembly=Mosaic.UI.Wpf"

The waveform visualizer controls are also mapped to the canonical URI, or can be referenced with:

xmlns:waveform="clr-namespace:Mosaic.UI.Wpf.Controls.WaveformVisualizer;assembly=Mosaic.UI.Wpf"

AvalonDock is shipped as a separate package/project and uses its own XAML URI:

xmlns:ad="https://github.com/blakepell/MosaicUIWpf"

For theme tokens (brushes, font sizes, etc.), declare:

xmlns:themes="http://schemas.apexgate.net/wpf/mosaic-ui"

and reference tokens like {DynamicResource {x:Static themes:MosaicTheme.ControlTextForegroundBrush}}.

---

Control Inventory

For detailed property/event/example documentation, read the individual file listed in the Details column.

| Control | Base Class | Category | Description | Details | |---|---|---|---|---| | AccentButton | Button | Input | Button with built-in accent color variants | AccentButton.md | | AdaptiveImage | Image | Media | Pixel-level HSL theme adaptation for images (light/dark mode) | AdaptiveImage.md | | AsteriskTextBlock | Control | Display | Displays masked text with a configurable mask character (default: ●) | AsteriskTextBlock.md | | AudioPlayer | Control | Media | Audio transport control with playlist, seek slider, playback events, and MediaPlayer backing | AudioPlayer.md | | AudioPlayerSpectrumAnalyzer | FrameworkElement | Media | WASAPI loopback spectrum analyzer intended to pair with AudioPlayer | AudioPlayer.md | | AutoCompleteBox | Control | Input | Searchable autocomplete combo box with async provider support | AutoCompleteBox.md | | Avatar | Button | Display | User avatar with image source or fallback initials | Avatar.md | | Badge | ContentControl | Display | Small inline status/count badge | Badge.md | | BindablePasswordBox | ContentControl | Input | Password field with a bindable Password string property | BindablePasswordBox.md | | ContentPanel | ContentControl | Layout | Themed content container with header, footer, separator, and corner styling | ContentPanel.md | | ChatThread | UserControl | Data | Chat conversation view with sent/received message templates | ChatThread.md | | CheckBoxList | ListBox | Input | Multi-select list that shows checkboxes beside each item | CheckBoxList.md | | ClipBorder | Border | Layout | Border that clips child content to its CornerRadius | ClipBorder.md | | ColorPicker | UserControl | Input | Visual color picker with hex input and preset colors | ColorPicker.md | | DatePicker | Control | Input | Mosaic date picker with popup month calendar and nullable selected date | DatePicker.md | | DocumentContainer | TabControl | Navigation | Closable, reorderable document tabs with active-document tracking | DocumentContainer.md | | EditableTextBlock | Control | Input | Inline editable text that toggles between view/edit mode | EditableTextBlock.md | | FavoriteCheckBox | CheckBox | Input | Symbol-based favorite/star toggle with configurable brushes | FavoriteCheckBox.md | | FileDropper | Control | Input | File drag-and-drop target with file type validation and command/event hooks | FileDropper.md | | Files | Control | Data | Directory file list with shell icons, sorting, selection, watcher refresh, and activation event | Files.md | | FlipPanel | ContentControl | Display | Animated flip panel with front and back content faces | FlipPanel.md | | GravatarImage | Image | Media | Loads and displays a Gravatar avatar from an email address | GravatarImage.md | | HexColorTextBox | ComboBox | Input | Editable hex color field (#RGB, #RRGGBB, #AARRGGBB) with shade drop-down | HexColorTextBox.md | | Hyperlink | ContentControl | Navigation | Clickable link that opens a URI or executes an ICommand | Hyperlink.md | | InertiaScrollViewer | ScrollViewer | Layout | ScrollViewer with animated inertia/momentum on mouse wheel | InertiaScrollViewer.md | | InfoCard | ContentControl | Display | Card with animated accent bar, title, header, body, and footer | InfoCard.md | | InputWaveformVisualizer | WaveformVisualizerBase | Media | Live waveform from a selectable Windows audio input device | WaveformVisualizer.md | | LabeledSeparator | ContentControl | Display | Horizontal separator with an embedded text label | LabeledSeparator.md | | LoopbackWaveformVisualizer | WaveformVisualizerBase | Media | Live waveform from the default Windows audio render device via WASAPI loopback | WaveformVisualizer.md | | MarkdownEditor | UserControl | Input | Markdown editor built on SyntaxEditor with toolbar, snippets, save helpers, and preview/copy actions | MarkdownEditor.md | | MarkdownViewer | Control | Display | WPF-native Markdown renderer backed by a copyable FlowDocument/RichTextBox | MarkdownViewer.md | | MessageBox | static class | Dialog | Themed drop-in replacement for System.Windows.MessageBox Show overloads | MessageBox.md | | NumericTextBox | TextBox | Input | Text box that accepts only numeric input with configurable decimal places | NumericTextBox.md | | ProgressRing | Control | Display | Indeterminate animated ring/spinner controlled by IsActive | ProgressRing.md | | PropertyGrid | Control | Data | Object property inspector using TypeDescriptor with category grouping | PropertyGrid.md | | RadialProgressBar | ProgressBar | Display | Circular progress bar with fill, pie, shape, and indeterminate modes | RadialProgressBar.md | | RelativePanel | Panel | Layout | Arranges children relative to each other via attached properties | RelativePanel.md | | ScalingTextBlock | TextBlock | Display | TextBlock that automatically lowers font size to fit available width | ScalingTextBlock.md | | SearchBox | TextBox | Input | Text box with watermark, clear button, and SearchExecuted event | SearchBox.md | | SettingsItem | ContentControl | Display | Settings row with icon, title, description, and slot for a control | SettingsItem.md | | ShadowPanel | ContentControl | Layout | Content container with configurable drop shadow effect | ShadowPanel.md | | ShadowTextBlock | TextBlock | Display | TextBlock with automatically applied drop shadow | ShadowTextBlock.md | | Shield | Control | Display | GitHub-style shield/badge with label and value sections | Shield.md | | SideMenu | UserControl | Navigation | Collapsible navigation side menu with search and drag-drop reorder | SideMenu.md | | SimpleStackPanel | Panel | Layout | Efficient stack panel with uniform Spacing between children | SimpleStackPanel.md | | SmallPanel | Panel | Layout | Overlay panel that stacks children in the same bounds | SmallPanel.md | | SplitButton | ContentControl | Input | Button with a separate drop-down chevron that opens a ContextMenu | SplitButton.md | | SplitPanel | Control | Layout | Two-pane resizable container with a draggable GridSplitter and bindable split ratio | SplitPanel.md | | StopwatchDisplay | ContentControl | Display | Real-time stopwatch with Start/Stop/Reset methods | StopwatchDisplay.md | | StringListEditor | ContentControl | Input | Editable list of strings with add/remove and duplicate/validation support | StringListEditor.md | | SymbolRating | Control | Input | Star/symbol rating control with hover preview and deselect | SymbolRating.md | | SyntaxEditor | TextEditor | Input | AvalonEdit-based code editor with Mosaic themes, bundled syntax highlighting, search, JSON commands, and line editing commands | SyntaxEditor.md | | TabControl | TabControl | Navigation | Mosaic-themed tab control with top/bottom active indicator | TabControl.md | | TagBox | Control | Input | Token/tag entry box with removable chips, duplicate control, and cancellable change events | TagBox.md | | ToggleButton | ToggleButton | Input | Mosaic-themed toggle button with checked/unchecked background | ToggleButton.md | | ToggleSwitch | Control | Input | Mobile-style on/off toggle switch with custom colors and MVVM | ToggleSwitch.md | | TwoPaneView | Control | Layout | Adaptive two-pane layout (side-by-side or stacked) | TwoPaneView.md | | ValidationSummaryPanel | ItemsControl | Data | Validation error collector and display panel with auto-hide | ValidationSummaryPanel.md | | VersionTextBlock | TextBlock | Display | Displays version string from a configurable assembly source | VersionTextBlock.md | | VT52Terminal | TextEditor | Terminal | Full ANSI/VT100/VT220/xterm terminal emulator (AvalonEdit-based) | VT52Terminal.md | | WindowTitleBar | UserControl | Windowing | Custom Mosaic window title bar with min/max/close and custom content slots | WindowTitleBar.md |

---

Behaviors

Behaviors live in the Mosaic.UI.Wpf.Behaviors namespace and add functionality to existing WPF controls without subclassing them — reach for one before authoring a new control. Most are Behavior<T> (attached inside <i:Interaction.Behaviors>); GridViewSortBehavior, WindowChromeBehavior, and BrushModifier are attached-property helpers (applied as behaviors:Foo.Bar="..."). The namespace is also mapped to the canonical Mosaic URI, so mosaic:-prefixed usage works too. See Behaviors.md for full property/usage details.

xmlns:behaviors="clr-namespace:Mosaic.UI.Wpf.Behaviors;assembly=Mosaic.UI.Wpf"
xmlns:i="http://schemas.microsoft.com/xaml/behaviors"

| Behavior | Attaches to | Description | Details | |---|---|---|---| | FocusBehavior | Control | Focuses the control when it loads | Behaviors.md | | BlinkingBehavior | FrameworkElement | Blinks an element by animating its opacity | Behaviors.md | | FrameworkElementZoomFontSizeOnMouseWheelBehavior | FrameworkElement | Ctrl+MouseWheel font-size zoom (clamped min/max) | Behaviors.md | | BrushModifier | Control/Border/Panel | Lightens/darkens the background brush by an HSL percentage | Behaviors.md | | TextBoxCopyBehavior | Button | Copies a target TextBox's (selected) text to the clipboard on click | Behaviors.md | | TextBoxClearTextOnEscapeBehavior | TextBoxBase | Clears the text box when Escape is pressed | Behaviors.md | | BlockCaretBehavior | TextBox | Terminal-style full-width block caret | Behaviors.md | | ItemsControlAutoScrollBehavior | ItemsControl | Auto-scrolls to the newest item when the collection changes | Behaviors.md | | ItemsControlFilterBehavior | TextBox | Debounced text filter over a target ItemsControl | Behaviors.md | | DataGridFilterBehavior | TextBox | Debounced full-text filter over a target DataGrid | Behaviors.md | | DataGridLastColumnFillBehavior | DataGrid | Stretches the last column to fill remaining width | Behaviors.md | | GridViewLastColumnFillBehavior | ListView | Auto-sizes the last GridView column | Behaviors.md | | GridViewSortBehavior | ListView/GridViewColumn | Click-header sorting for a GridView | Behaviors.md | | ListViewDeleteBehavior | ListView | Deletes selected items on the Delete key (optional confirm) | Behaviors.md | | OpenContextMenuBehavior | ButtonBase | Opens the button's ContextMenu on click | Behaviors.md | | OpenWindowBehavior | ButtonBase/MenuItem | Opens a Window of a given type on click (modal/modeless) | Behaviors.md | | CloseWindowOnEscapeBehavior | Window | Closes the window on Escape | Behaviors.md | | WindowChromeBehavior | Window | Custom borderless chrome, themed brushes, rounded corners | Behaviors.md | | AvalonTextEditorBindingBehavior | AvalonEdit TextEditor | Bindable text, selection, selected text, and caret offset | AvalonEditBehaviors.md | | AvalonEditPropertiesBehavior | AvalonEdit TextEditor | Binds caret brush and hyperlink enablement | AvalonEditBehaviors.md | | AvalonEditVtTerminalBehavior | AvalonEdit TextEditor | Applies a retro VT/CRT visual skin | AvalonEditBehaviors.md | | AvalonEditCopyBehavior | Button | Copies a target TextEditor's (selected) text to the clipboard on click | AvalonEditBehaviors.md |

File name ≠ class name for four behaviors: AvalonEditBindingBehavior.cs → AvalonTextEditorBindingBehavior, TextBoxClearOnEscapeBehavior.cs → TextBoxClearTextOnEscapeBehavior, CloseWindowOnEscape.cs → CloseWindowOnEscapeBehavior, ButtonOpenContextMenu.cs → OpenContextMenuBehavior. Use the class name in XAML.

Integration Packages

These are not main-assembly controls, but are part of the Mosaic usage surface and have demo examples.

| Item | Kind | Namespace / URI | Description | Details | |---|---|---|---|---| | DockingManager / MosaicTheme | Separate package/project | https://github.com/blakepell/MosaicUIWpf | Mosaic-themed AvalonDock fork/integration for IDE-style document and tool-window docking | AvalonDock.md |

Support Controls

These public controls exist for native style dictionaries and low-level template composition. Prefer the higher-level controls in the main inventory unless you are editing Mosaic's native styles or need this exact primitive.

| Control | Base Class | Primary Use | Details | |---|---|---|---| | SliderRepeatButton | RepeatButton | Slider track repeat buttons with corner orientation metadata | SupportControls.md | | SystemDropShadowChrome | Decorator | WPF-style chrome shadow rendering for popups and native templates | SupportControls.md | | WDScrollViewer | ScrollViewer | Native TreeView template scrolling with optional wheel animation | SupportControls.md |

---

Theme Tokens

Reference theme brushes via DynamicResource using MosaicTheme static keys:

xmlns:themes="http://schemas.apexgate.net/wpf/mosaic-ui"

<!-- Foreground / background -->
Foreground="{DynamicResource {x:Static themes:MosaicTheme.ControlTextForegroundBrush}}"
Background="{DynamicResource {x:Static themes:MosaicTheme.ControlBackgroundBrush}}"

<!-- Border -->
BorderBrush="{DynamicResource {x:Static themes:MosaicTheme.ControlBorderBrush}}"

<!-- Accent / status -->
Fill="{DynamicResource {x:Static themes:MosaicTheme.AccentBrush}}"
Fill="{DynamicResource {x:Static themes:MosaicTheme.SuccessBrush}}"
Fill="{DynamicResource {x:Static themes:MosaicTheme.WarningBrush}}"
Fill="{DynamicResource {x:Static themes:MosaicTheme.ErrorBrush}}"
Fill="{DynamicResource {x:Static themes:MosaicTheme.InfoBrush}}"

<!-- Font sizes -->
FontSize="{DynamicResource {x:Static themes:MosaicTheme.FontSizeSmall}}"
FontSize="{DynamicResource {x:Static themes:MosaicTheme.FontSizeMedium}}"
FontSize="{DynamicResource {x:Static themes:MosaicTheme.FontSizeLarge}}"

---

App Setup

Consumer apps wire Mosaic by:

1. Using MosaicApp<TSettings, TViewModel> as the Application base in App.xaml.
2. Merging a ThemeManager into application resources.
3. Placing mosaic:WindowTitleBar + WindowChromeBehavior in MainWindow.

See the mosaic-setup-project skill for the full wiring procedure.

---

Quick Tips

• Always use DynamicResource for theme tokens — switching themes requires live updates.
• CustomControls (most controls) support re-templating; UserControl-based controls (ColorPicker, ChatThread, MarkdownEditor, SideMenu, WindowTitleBar) do not.
• VT52Terminal requires the separate sub-namespace Mosaic.UI.Wpf.Controls.VT52Terminal.
• InputWaveformVisualizer and LoopbackWaveformVisualizer live in Mosaic.UI.Wpf.Controls.WaveformVisualizer, but are mapped to the canonical Mosaic XAML URI.
• AvalonDock lives in Mosaic.UI.Wpf.AvalonDock / package MosaicUIWpf.AvalonDock and uses xmlns:ad="https://github.com/blakepell/MosaicUIWpf".
• AdaptiveImage requires ThemeManager in the DI container (AppServices).
• PropertyGrid reads [Category], [Description], and [PropertyGridAttribute] attributes on the target object.
• SideMenu uses ContentTypeIsSingleton + AppServices DI for singleton view navigation in the demo.
• Public support controls such as WDScrollViewer, SliderRepeatButton, and SystemDropShadowChrome are primarily used by native theme dictionaries; see SupportControls.md.