> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/code/controls/tabcontrol.md).

# TabControl

## Introduction

TabControl shows a strip of tab headers and the page of the selected tab. It inherits from [ItemsControl](https://docs.flatredball.com/gum/code/controls/itemscontrol.md). Each entry in `Items` creates one `TabItem` header in the strip and one `TabPage` in the content area, paired by position.

{% hint style="info" %}
Available in December 2026, or now if building Gum from source.
{% endhint %}

## Code Example: Adding Tabs

`AddTab` adds a tab with a header and the content shown when the tab is selected. Adding tabs does not select one, so the example sets `SelectedIndex`.

```csharp
// Initialize
var tabControl = new TabControl();
tabControl.AddToRoot();
tabControl.X = 50;
tabControl.Y = 50;
tabControl.Width = 400;
tabControl.Height = 200;

var playButton = new Button();
playButton.Text = "Play";
tabControl.AddTab("Game", playButton);

var volumeLabel = new Label();
volumeLabel.Text = "Volume";
tabControl.AddTab("Audio", volumeLabel);

tabControl.SelectedIndex = 0;
```

`AddTab` returns the new `TabItem`. Content can be a Forms control, a `GraphicalUiElement`, or a `TabPage`.

## Items

`Items` is the only collection to edit. `TabItems` and `Pages` are read-only views of the tabs and pages that `Items` created.

An object added to `Items` makes a tab whose header shows the object's `ToString()`. `VisualTemplate` changes the header and `ContentTemplate` creates the page content. Both receive the item, which also becomes the `BindingContext` of the page.

```csharp
using Gum.Forms;
```

```csharp
// Initialize
var tabControl = new TabControl();
tabControl.AddToRoot();
tabControl.ContentTemplate = new VisualTemplate(item =>
{
    var label = new Label();
    label.Text = "Page for " + item;
    return label.Visual;
});

tabControl.Items.Add("Inventory");
tabControl.Items.Add("Map");
tabControl.SelectedIndex = 0;
```

As with [ListBox](https://docs.flatredball.com/gum/code/controls/listbox.md), assigning a bound collection to `Items` replaces tabs that were authored in the Gum tool.

Setting `TabItem.Header` in code, or passing a header to `AddTab`, translates the string when a `LocalizationService` is active. A header made from an item in `Items` is not translated. See [Localization](https://docs.flatredball.com/gum/code/localization.md).

## Selection

`SelectedIndex` and `SelectedObject` read and set the selected tab. A TabControl authored in the Gum tool with no `SelectedIndex` set selects the first tab. Tabs added from code start unselected, so `SelectedIndex` is `-1` until you set it. `SelectedIndex` is also `-1` when no tab is selected, and an out-of-range value is ignored. Removing the selected tab leaves nothing selected. `SelectionChanged` is raised whenever the selection changes, including when the user clicks a tab.

```csharp
// Initialize, using the tabControl from above
var statusLabel = new Label();
statusLabel.AddToRoot();
statusLabel.Y = 300;

tabControl.SelectionChanged += (_, args) =>
{
    statusLabel.Text = "Selected tab " + tabControl.SelectedIndex;
};
```

## Keyboard and Gamepad

A focused TabControl selects the previous or next enabled tab with the left and right arrow keys, the gamepad DPad, or the left stick. Selection stops at the first and last tab. For setup and the keys and buttons each device uses, see [Keyboard Support](https://docs.flatredball.com/gum/code/events-and-interactivity/keyboard-support.md) and [Gamepad Support](https://docs.flatredball.com/gum/code/events-and-interactivity/gamepad-support.md).

## Styling

TabControl, TabItem, and TabPage are styled by your theme, and the themes that ship with Gum style all three. To build tabs and pages in the Gum tool, see [TabControl](https://docs.flatredball.com/gum/gum-tool/forms-controls/tabcontrol.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flatredball.com/gum/code/controls/tabcontrol.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
