Devexpress Wpf Tab Control

DevExpress WPF Tab Control

DXTabControl is a tabbed navigation control: a header panel with selectable headers across the top (or side), and a content area that shows the active page. Headers can overflow into multiple lines, scroll, or shrink (one of three views); tabs can carry icons, custom colors, close buttons, and drag-drop reordering. Tabs can be defined explicitly as DXTabItem children, populated from an IList, or generated from a data collection via ItemsSource + templates.

> Window hosting: For proper visual integration (themed title bar, ContentHeader/Footer aligning with the title bar, control box buttons in the tab bar), the host window should be dx:ThemedWindow, not a plain Window. Use ThemedWindow even when you don't otherwise need its features.

This skill covers project setup (with the ThemedWindow requirement), tab definition (XAML / Items / ItemsSource), the three layout views, and appearance customization.

When to Use This Skill

Use this skill when you need to:

• Add a tabbed page UI to a window
• Generate tabs dynamically from a view-model collection (ItemsSource)
• Allow users to close (AllowHide) and reorder tabs
• Pick a view (MultiLine / Scroll / Stretch) for header overflow behavior
• Color or theme individual tabs (AccentColor, BorderColor)
• Add custom content to the tab bar (left/right control box, content header/footer)

Prerequisites & Installation

NuGet Packages

| Package | Provides | |---------|---------| | DevExpress.Wpf.Core | DXTabControl, DXTabItem, ThemedWindow |

dotnet add package DevExpress.Wpf.Core

A valid DevExpress license is required. All DevExpress packages in a project must share the same version.

Host Window — Use ThemedWindow, Not Window

The host window should be dx:ThemedWindow. DXTabControl integrates with ThemedWindow for:

• Themed title bar continuous with the tab header area
• ControlBoxLeftTemplate / ControlBoxRightTemplate rendering correctly in the title bar
• Tab drag-out creating a properly themed pop-out window
• Theming hooks via IThemedWindowSupport

Convert the main window:

And in MainWindow.xaml.cs:

using DevExpress.Xpf.Core;

public partial class MainWindow : ThemedWindow {
    public MainWindow() { InitializeComponent(); }
}

> A plain Window will work (the tabs render, the control responds to input), but you'll get visual artifacts like a double title bar, mismatched colors between the title bar and the tab strip, and broken hit-testing for ControlBoxLeft/RightTemplate. Always use ThemedWindow when hosting DXTabControl.

XAML Namespaces

xmlns:dx="http://schemas.devexpress.com/winfx/2008/xaml/core"

| Prefix | Use for | |---|---| | dx: | ThemedWindow, DXTabControl, DXTabItem, TabControlMultiLineView, TabControlScrollView, TabControlStretchView, DXImage |

Three Ways to Define Tabs — Picker

| Approach | When to use | |---|---| | Explicit DXTabItem children in XAML | Tabs are static and few; content is XAML-authored markup | | Add to Items in code | Same as above but built programmatically | | ItemsSource + templates | Tabs come from a view-model collection (MDI document workspace, master-list editor); ItemHeaderTemplate defines the header, ItemTemplate defines the content |

See [defining-tabs.md](references/defining-tabs.md) for the full picker and examples.

Three Views — Header Overflow Behavior

| View | When tabs don't fit | Set via | |---|---|---| | TabControlMultiLineView | Wrap into multiple lines | ` | | **TabControlScrollView** | Show left/right scroll buttons; horizontal or vertical orientation | | | **TabControlStretchView** | Shrink tab widths; supports pinning + drag-drop | ` |

    
        
    
    ...

Full details in [views.md](references/views.md).

Before You Start — Ask the Developer

1. Static or dynamic tabs? Static set in XAML; dynamic from a view-model — pick ItemsSource + templates.
2. How many tabs are expected? Many tabs (10+) → Scroll or Stretch view; a few → MultiLine or default.
3. Should tabs be closable / draggable / pinned? Stretch view supports drag-drop + pin; close button via DXTabItem.AllowHide.
4. Tab caching: should content be loaded once and kept alive when switching? See TabContentCacheMode.
5. Visual customization: per-tab colors? Custom areas around the tab strip (left/right control box, content header/footer)? See [appearance.md](references/appearance.md).

Documentation & Navigation Guide

Getting Started

Refer to [references/getting-started.md](references/getting-started.md)

When you need to:

• Install the NuGet package
• Convert the window to ThemedWindow
• Place a first DXTabControl with two tabs

Defining Tabs — XAML, Items, ItemsSource

Refer to [references/defining-tabs.md](references/defining-tabs.md)

When you need to:

• Pick between explicit DXTabItem children and ItemsSource + templates
• Bind tabs to a view-model collection
• Add icons / close buttons / per-tab content templates
• Control caching (TabContentCacheMode)

Views — MultiLine, Scroll, Stretch

Refer to [references/views.md](references/views.md)

When you need to:

• Pick a view based on how tabs should overflow
• Configure header location (top / bottom / left / right)
• Enable scroll buttons, mouse-wheel scrolling, animation
• Enable drag-drop / pinning (Stretch only)

Appearance Customization

Refer to [references/appearance.md](references/appearance.md)

When you need to:

• Color individual tabs (AccentColor, BorderColor)
• Theme tabs without overriding theme resources (NormalBackgroundTemplate, HoverBackgroundTemplate, ...)
• Add content to the left/right of the tab strip (ControlBoxLeftTemplate, ControlBoxRightTemplate)
• Add header/footer rows around the content area (ContentHeaderTemplate, ContentFooterTemplate)

Quick Start

Static Tabs

Dynamic Tabs from a Data Collection

public class MainViewModel {
    public ObservableCollection Documents { get; } = new() {
        new DocumentViewModel { Title = "Invoice 1001" },
        new DocumentViewModel { Title = "Invoice 1002" }
    };
}

Key API Surface

DXTabControl Members

| Member | Use | |---|---| | Items | Collection of DXTabItem (or auto-generated when using ItemsSource) | | ItemsSource | Bind to a data collection — tabs are generated from items | | ItemHeaderTemplate | Template for each tab's header when using ItemsSource | | ItemTemplate | Template for each tab's content when using ItemsSource | | View | Layout / behavior — TabControlMultiLineView, TabControlScrollView, TabControlStretchView | | SelectedIndex / SelectedItem | Active tab | | TabContentCacheMode | Default (no cache), CacheAllTabs, CacheTabsOnSelecting | | ControlBoxLeftTemplate / ControlBoxRightTemplate | Custom content at the left / right of the tab strip | | ContentHeaderTemplate / ContentFooterTemplate | Custom content above / below the page area | | ControlBoxPanelTemplate | Custom elements inside the tab panel | | SelectionChanging (event) | Cancel-able event fired before selection changes | | SelectionChanged (event) | Fired after selection changes |

DXTabItem Members

| Member | Use | |---|---| | Header | Header text (or arbitrary object — use HeaderTemplate to template it) | | HeaderTemplate | Template for the header content | | Content | Page content | | ContentTemplate | Template for the content | | Glyph / GlyphTemplate | Icon shown in the header | | AllowHide | Show the close (×) button on the tab | | IsHidden | Programmatically hide a tab | | HeaderMenuContent | Content for the header dropdown menu entry | | AccentColor | Background/foreground tint for this tab | | BorderColor | Border color for this tab | | NormalBackgroundTemplate / HoverBackgroundTemplate / SelectedBackgroundTemplate / FocusedBackgroundTemplate | Per-state custom theming |

Views

| View | Key properties | |---|---| | TabControlMultiLineView | FixedHeaders | | TabControlScrollView | ScrollButtonShowMode, AllowScrollOnMouseWheel, AllowAnimation, HeaderAutoFill, HeaderOrientation | | TabControlStretchView | TabNormalSize, TabMinSize, SelectedTabMinSize, PinnedTabSize, DragDropMode, DragDropRegion, NewWindowStyle, NewTabControlStyle; PinMode (attached, set on the tab item via dx:TabControlStretchView.PinMode) | | TabControlViewBase (base for all) | HeaderLocation (Top, Bottom, Left, Right) |

Common Patterns

Pattern 1: Document Workspace with Closable Tabs

ItemContainerStyle sets AllowHide and Header on every generated DXTabItem. Closing a tab raises TabHiding / TabHidden events.

Pattern 2: Tabs with Icons

    ...

dx:DXImage loads from the DevExpress image library; otherwise pass a regular ImageSource.

Pattern 3: Cached Tab Content for Fast Switching

    ...

All tab contents are constructed once and kept in memory. Use when re-creating content is expensive (e.g., heavy data grids).

Pattern 4: Header Panel on the Side

    
        
    
    ...

Pattern 5: Custom Buttons in the Tab Strip

    
        
            
                
                
            
        
    
    ...

Troubleshooting

| Symptom | Cause | Solution | |---|---|---| | Two title bars, mismatched colors above the tabs | Host is Window, not ThemedWindow | Convert the window — see Getting Started. | | ControlBoxLeftTemplate doesn't show | Host is Window, not ThemedWindow — left/right control box renders in the title bar | Convert to ThemedWindow. | | ItemsSource items show but headers are blank | ItemHeaderTemplate not set (or doesn't bind the right property) | Set ItemHeaderTemplate with a DataTemplate that binds to the header property. | | Tab content disappears on tab switch and reloads when switching back | Default is to re-create the content on every selection | Set TabContentCacheMode="CacheAllTabs" (or CacheTabsOnSelecting). | | Headers overflow off-screen | Default view (Scroll) without scroll buttons visible — ScrollButtonShowMode may be Never | Use AutoHideBothButtons, or switch to MultiLine view. | | Drag-drop doesn't work | View is MultiLine or Scroll — drag-drop is Stretch-only | Use TabControlStretchView and set DragDropMode. | | AccentColor doesn't show / is ignored | Set as a Brush instead of a Color | Use a Color value (AccentColor="Red"), not a brush. | | SelectionChanging cancel doesn't work | Setting e.Cancel = false (default) or handling SelectionChanged instead | Use SelectionChanging; set e.Cancel = true. | | Glyph doesn't render | Path / URI wrong, or used a Brush where an ImageSource is expected | Use {dx:DXImage Image=...} or a proper pack: URI to an embedded image. |

Constraints & Rules

CRITICAL — follow these rules in every interaction:

1. Build verification: After changes, run dotnet build and report errors before claiming success.
2. Target framework: Windows-only (net{X}-windows, UseWPF=true).
3. Use ThemedWindow as the host when adding DXTabControl. Plain Window "works" but has visual artifacts; never the right choice for production.
4. NuGet: install DevExpress.Wpf.Core (DXTabControl lives in core).
5. Default to Scroll view for unknown tab counts; switch to MultiLine or Stretch based on the design's overflow handling.
6. For dynamic tabs, use ItemsSource + ItemHeaderTemplate + ItemTemplate — don't manipulate Items directly when there's a backing view-model collection.
7. AccentColor and BorderColor are Color values, not brushes.
8. Drag-drop, pinning, and pop-out windows are Stretch-view-only — TabControlStretchView is the only view that exposes these features.
9. Set TabContentCacheMode explicitly when content re-creation is expensive — the default is no caching.

Using DevExpress Documentation MCP

• Search: devexpress_docs_search(technology="WPF", query="DXTabControl view header customization")
• Fetch: devexpress_docs_get_content(url="https://docs.devexpress.com/WPF/7975")

Use MCP for: drag-drop deep-dives (DragDropMode, DragDropRegion), the DXTabbedWindow (https://docs.devexpress.com/content/WPF/DevExpress.Xpf.Core.DXTabbedWindow?md=true), restricting selection (SelectionChanging), header menu customization, and adding/removing tabs at runtime.

---

Next Steps

Start with [Getting Started](references/getting-started.md) for the ThemedWindow conversion and a first tab control. Then [Defining Tabs](references/defining-tabs.md) for static vs. dynamic patterns. [Views](references/views.md) for overflow behavior. [Appearance](references/appearance.md) for colorized tabs, custom theming, and templated regions.

Source & license

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

• Author: DevExpress
• Source: DevExpress/agent-skills
• License: MIT
• Homepage: https://www.devexpress.com

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