Segmented Control¶

The SegmentedControl element lets users switch between multiple card-based views without triggering a page refresh.

SegmentedControl Class¶

SegmentedControl ¶

SegmentedControl(*, title: str, segments: list[Segment], active_segment_index: Optional[int] = 0, controls_position: ElementHorizontalPosition = ElementHorizontalPosition.LEFT, max_controls_width: Optional[int] = None, reference_id: Optional[str] = '', **kwargs)

A SegmentedControl Element for switching between multiple Card-based views.

The SegmentedControl allows users to switch between different Segments (Card-based views) without triggering a page refresh. Each segment contains arbitrary content like tables, plots, and input elements.

Parameters:

title (str) –

The title of the segmented control element.
segments (list[Segment]) –

List of Segment objects to display.
active_segment_index (Optional[int], default: 0 ) –

Index of the initially active segment (0-based). Defaults to 0.
controls_position (ElementHorizontalPosition, default: LEFT ) –

Horizontal alignment of the segment buttons (LEFT/CENTER/RIGHT). Defaults to LEFT.
max_controls_width (Optional[int], default: None ) –

Maximum width of the controls container in pixels. When exceeded, horizontal scrolling is enabled. Defaults to None (no limit).
reference_id (Optional[str], default: '' ) –

A user-defined reference ID for unique identification, defaults to ''.
kwargs –

Additional parameters.

to_json ¶

to_json() -> dict

Convert the element to JSON.

Segment Class¶

Segment ¶

Segment(label: str, title: str, content: List[Union[Element, Row]], subtitle: str = '', description: str = '', _id: Optional[str] = None, show_title: bool = True, show_description: bool = True, page_update: Optional[PageUpdateCallback] = None, disable_next: bool = False, updater_text: Optional[str] = None, filters: Optional[List[InputElement]] = None, filter_update: Optional[Callable] = None, show_comments: bool = False, show_export: bool = False, show_share: bool = False, info_content: Optional[str] = None)

A Segment is a special type of Card used within a SegmentedControl.

Segments are Card-based views that can contain arbitrary content (tables, plots, inputs, etc.). Each segment has a label that appears in the segmented control buttons.

Parameters:

label (str) –

The label text displayed on the segment button.

to_json ¶

to_json() -> dict

Convert the segment to JSON, including the label.

Basic Usage¶

from virtualitics_sdk import SegmentedControl
from virtualitics_sdk.page.card import Segment

# Create segments
overview = Segment(label="Overview")
overview.add_content([
    RichText("## Summary"),
    Infographic(id="kpis", title="KPIs", data=[...])
])

details = Segment(label="Details")
details.add_content([
    Table(id="detail_table", data=detail_df)
])

# Create the segmented control
tabs = SegmentedControl(
    title="Data Views",
    segments=[overview, details],
    active_segment_index=0
)

Controls Position¶

Control the horizontal alignment of the segment buttons:

from virtualitics_sdk.elements.element import ElementHorizontalPosition

# Left-aligned (default)
tabs = SegmentedControl(
    title="Views",
    segments=[seg1, seg2],
    controls_position=ElementHorizontalPosition.LEFT
)

# Center-aligned
tabs = SegmentedControl(
    title="Views",
    segments=[seg1, seg2],
    controls_position=ElementHorizontalPosition.CENTER
)

# Right-aligned
tabs = SegmentedControl(
    title="Views",
    segments=[seg1, seg2],
    controls_position=ElementHorizontalPosition.RIGHT
)

Scrollable Controls¶

When you have many segments, set max_controls_width to enable horizontal scrolling:

tabs = SegmentedControl(
    title="Many Tabs",
    segments=[seg1, seg2, seg3, seg4, seg5, seg6],
    max_controls_width=600  # pixels — scroll if controls exceed this width
)

Adding Content to Segments¶

Each Segment behaves like a Card. Use add_content() to add elements:

segment = Segment(label="Charts")

# Add a single element
segment.add_content(PlotlyPlot(figure=fig))

# Add multiple elements in a row
segment.add_content([plot1, plot2])

# Add with custom width ratios
segment.add_content([narrow_elem, wide_elem], ratio=[1, 3])

Complete Example¶

from virtualitics_sdk import (
    Step, Page, Section, Card, Table, PlotlyPlot,
    SegmentedControl, RichText, Infographic, InfographData
)
from virtualitics_sdk.page.card import Segment
import plotly.express as px


class AnalysisStep(Step):
    def run(self, flow_metadata):
        df = self._inLink.data.data

        # Summary segment
        summary_seg = Segment(label="Summary")
        summary_seg.add_content([
            Infographic(
                id="metrics",
                title="Key Metrics",
                data=[
                    InfographData(label="Total", value=f"${df['sales'].sum():,.0f}"),
                    InfographData(label="Average", value=f"${df['sales'].mean():,.0f}"),
                ]
            )
        ])

        # Chart segment
        chart_seg = Segment(label="Charts")
        fig = px.bar(df, x="product", y="sales", title="Sales by Product")
        chart_seg.add_content([PlotlyPlot(figure=fig)])

        # Data segment
        data_seg = Segment(label="Raw Data")
        data_seg.add_content([Table(data=df)])

        tabs = SegmentedControl(
            title="Analysis",
            segments=[summary_seg, chart_seg, data_seg],
            active_segment_index=0
        )

        return Page(
            title="Analysis",
            sections=[
                Section(title="Results", cards=[
                    Card(title="Analysis", content=[tabs])
                ])
            ]
        )

Validation Rules¶

Must have at least one segment
active_segment_index must be within bounds (0 to len(segments) - 1)
Segment labels must be unique
max_controls_width must be a positive integer if provided

Best Practices¶

Unique labels: Each segment must have a distinct label
Limit segments: More than 5-6 segments becomes hard to navigate — consider using steps instead
Default tab: Set active_segment_index to the most relevant view
Consistent content: Keep segment content at similar complexity levels
Scrollable controls: Use max_controls_width when you have more than 4 segments

Segmented Control¶