Tesserae - Pivot

Pivot

Description

The Pivot component is a tab-based container used to organize and display content panels within a user interface. It allows users to switch between different views or sections by clicking on tab titles, with options to customize tab alignment (normal, justified, or centered) and to control caching of tab content. Use it when you need to present segmented information in a compact, navigable format.

Usage

Instantiate the Pivot component using the static helper method from the Tesserae.UI static class. Add tabs by chaining the .Pivot() method with a unique tab identifier, a title generated with PivotTitle(), and a function that returns the tab content. The Pivot component is designed to be highly configurable with additional style methods for layout management.

Below is a simple usage example:

pivot-sample.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            new PivotExample().Run();
        }
    }

    public class PivotExample
    {
        public void Run()
        {
            // Create a Pivot with three tabs
            var pivot = Pivot()
                .Pivot("first-tab", PivotTitle("First Tab"), () => TextBlock("Content for First Tab"))
                .Pivot("second-tab", PivotTitle("Second Tab"), () => TextBlock("Content for Second Tab"))
                .Pivot("third-tab", PivotTitle("Third Tab"), () => TextBlock("Content for Third Tab"));

            // Optionally customize the pivot style: centered alignment
            pivot.Centered();

            // Render and attach the Pivot component to the DOM
            var sampleComponent = pivot;
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }
}

API reference

class

Pivot

public sealed class Pivot : IComponent, ISpecialCaseStyling, IBindableComponent<string>

A horizontal tabbed surface with one tab visible at a time.

Namespace: Tesserae
Implements: IComponent, ISpecialCaseStyling, IBindableComponent<string>

Constructors

Name	Description
Pivot	Initializes a new instance of this class.

Constructor

Pivot

public Pivot()

Initializes a new instance of this class.

Properties

Name	Description
SelectedTab	Gets or sets the selected tab.
StylingContainer	Gets or sets the styling container.
PropagateStylesToWrapper	Gets whether a sizing helper applied to this component should tag it so a wrapper-building container hoists the style onto the wrapper.
TabIds	Gets the ids of the tabs, in the order they appear on the tab strip.

Property

Pivot.SelectedTab

public string SelectedTab

Gets or sets the selected tab.

Property

Pivot.StylingContainer

public HTMLElement StylingContainer { get; }

Gets or sets the styling container.

Property

Pivot.PropagateStylesToWrapper

public bool PropagateStylesToWrapper

Gets whether a sizing helper applied to this component should tag it so a wrapper-building container hoists the style onto the wrapper.

Property

Pivot.TabIds

public string[] TabIds

Gets the ids of the tabs, in the order they appear on the tab strip.

Methods

Name	Description
Justified	Configures the component to justified.
Centered	Configures the component to centered.
HideIfSingle	Hides the if single.
Reorderable	Lets the user reorder the tabs by dragging their titles along the tab strip. Pass `false` to turn dragging back off — the tabs keep the order they were dragged into. Use `OnReorder` to persist the new order.
OnReorder	Registers a callback invoked after the user drags a tab into a new position. Requires `Reorderable`.
MoveTab	Moves the tab with the given id to `newIndex` on the tab strip, clamping the index into range. Does not raise `OnReorder`, which reports user-driven reordering only.
EnableCtrlTabSwitching	Enables Ctrl+Alt+Right / Ctrl+Alt+Left to cycle through tabs in order while the pivot is mounted and focus is inside its container (or no element is focused). Safe to call multiple times — the handler is only registered once.
RefreshPivotSizes	Refreshes the pivot sizes.
RequestCloseTab	Invoked by the tab's close button. When the tab supplies an `OnBeforeClose` guard (e.g. to confirm discarding unsaved changes), it is awaited first and the tab is only removed if the guard resolves `true`. Tabs without a guard close immediately, exactly as before.
RemoveTab	Removes the given tab from the component.
OnBeforeNavigate	Registers a callback invoked when the before navigate event fires.
OnNavigate	Registers a callback invoked when the navigate event fires.
Select	Configures the component to select.
AsObservable	Returns an observable that tracks the id of the currently-selected tab.
SetBoundValue	Programmatically selects a tab by id as part of a two-way binding.
Render	Renders the component's root HTML element.

Method

Pivot.Justified

public Pivot Justified()

Configures the component to justified.

Method

Pivot.Centered

public Pivot Centered()

Configures the component to centered.

Method

Pivot.HideIfSingle

public Pivot HideIfSingle()

Hides the if single.

Method

Pivot.Reorderable

public Pivot Reorderable(bool reorderable = true)

Lets the user reorder the tabs by dragging their titles along the tab strip. Pass false to turn dragging back off — the tabs keep the order they were dragged into. Use OnReorder to persist the new order.

Method

Pivot.OnReorder

public Pivot OnReorder(PivotEventHandler<PivotReorderEvent> onReorder)

Registers a callback invoked after the user drags a tab into a new position. Requires Reorderable.

Method

Pivot.MoveTab

public Pivot MoveTab(string id, int newIndex)

Moves the tab with the given id to newIndex on the tab strip, clamping the index into range. Does not raise OnReorder, which reports user-driven reordering only.

Method

Pivot.EnableCtrlTabSwitching

public Pivot EnableCtrlTabSwitching()

Enables Ctrl+Alt+Right / Ctrl+Alt+Left to cycle through tabs in order while the pivot is mounted and focus is inside its container (or no element is focused). Safe to call multiple times — the handler is only registered once.

Method

Pivot.RefreshPivotSizes

public void RefreshPivotSizes()

Refreshes the pivot sizes.

Method

Pivot.RequestCloseTab

private void RequestCloseTab(Tab tab)

Invoked by the tab's close button. When the tab supplies an OnBeforeClose guard (e.g. to confirm discarding unsaved changes), it is awaited first and the tab is only removed if the guard resolves true. Tabs without a guard close immediately, exactly as before.

Method

Pivot.RemoveTab

public void RemoveTab(string id)

Removes the given tab from the component.

Method

Pivot.OnBeforeNavigate

public Pivot OnBeforeNavigate(PivotEventHandler<PivotBeforeNavigateEvent> onBeforeNavigate)

Registers a callback invoked when the before navigate event fires.

Method

Pivot.OnNavigate

public Pivot OnNavigate(PivotEventHandler<PivotNavigateEvent> onNavigate)

Registers a callback invoked when the navigate event fires.

Method

Pivot.Select

public Pivot Select(string id, bool refresh = false)

Configures the component to select.

Method

Pivot.AsObservable

public IObservable<string> AsObservable()

Returns an observable that tracks the id of the currently-selected tab.

Method

Pivot.SetBoundValue

public void SetBoundValue(string value)

Programmatically selects a tab by id as part of a two-way binding.

Method

Pivot.Render

public HTMLElement Render()

Renders the component's root HTML element.

Samples

Basic Pivot Usage Sample

This sample demonstrates creating a basic Pivot with three tabs. It sets up the Pivot, adds tabs with simple text content, applies centered tab alignment, and renders the component to the document body.

pivot-2-sample.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            new PivotBasicSample().Run();
        }
    }

    public class PivotBasicSample
    {
        public void Run()
        {
            // Create and configure the Pivot component with three tabs
            var pivot = Pivot()
                .Pivot("tab1", PivotTitle("Tab 1"), () => TextBlock("This is the content of Tab 1"))
                .Pivot("tab2", PivotTitle("Tab 2"), () => TextBlock("This is the content of Tab 2"))
                .Pivot("tab3", PivotTitle("Tab 3"), () => TextBlock("This is the content of Tab 3"))
                .Centered(); // Center the tab titles

            // Append the rendered pivot to the document body
            var sampleComponent = pivot;
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }
}

Advanced Usage: Cached vs. Not Cached Tabs

This sample shows how to configure tabs with caching options. Cached tabs store their content after the initial render to improve performance, while non-cached tabs re-render their content every time they are selected.

pivot-3-sample.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            new PivotCachedSample().Run();
        }
    }

    public class PivotCachedSample
    {
        public void Run()
        {
            // Create a Pivot with two tabs, one cached and one non-cached.
            var pivot = Pivot()
                .Pivot("cached-tab", PivotTitle("Cached Tab"),
                       () => TextBlock(DateTimeOffset.UtcNow.ToString()).Regular(), cached: true)
                .Pivot("non-cached-tab", PivotTitle("Non Cached Tab"),
                       () => TextBlock(DateTimeOffset.UtcNow.ToString()).Regular(), cached: false);

            // Append the rendered pivot to the document body
            var sampleComponent = pivot;
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }
}

Pivot

Description

Usage

API reference

Constructors

Pivot

Properties

Pivot.SelectedTab

Pivot.StylingContainer

Pivot.PropagateStylesToWrapper

Pivot.TabIds

Methods

Pivot.Justified

Pivot.Centered

Pivot.HideIfSingle

Pivot.Reorderable

Pivot.OnReorder

Pivot.MoveTab

Pivot.EnableCtrlTabSwitching

Pivot.RefreshPivotSizes

Pivot.RequestCloseTab

Pivot.RemoveTab

Pivot.OnBeforeNavigate

Pivot.OnNavigate

Pivot.Select

Pivot.AsObservable

Pivot.SetBoundValue

Pivot.Render

Samples

Basic Pivot Usage Sample

Advanced Usage: Cached vs. Not Cached Tabs

See also