TabsPlugin: fix overflow and support vertical tabs (#9511)

## 📝 Summary

<!--
If this PR closes any issues, list them here by number (e.g., Closes
#123).

Detail the specific changes made in this pull request. Explain the
problem addressed and how it was resolved. If applicable, provide before
and after comparisons, screenshots, or any relevant details to help
reviewers understand the changes easily.
-->
Closes #9482 and support vertical tabs

<img width="926" height="689" alt="image"
src="https://github.com/user-attachments/assets/610949d1-a6e5-4a6a-8dc3-35c82837e705"
/>

<img width="573" height="196" alt="image"
src="https://github.com/user-attachments/assets/9086dc72-8697-4a25-b085-1b3a394f01e4"
/>

## 📋 Pre-Review Checklist
<!-- These checks need to be completed before a PR is reviewed -->

- [x] For large changes, or changes that affect the public API: this
change was discussed or approved through an issue, on
[Discord](https://marimo.io/discord?ref=pr), or the community
[discussions](https://github.com/marimo-team/marimo/discussions) (Please
provide a link if applicable).
- [x] Any AI generated code has been reviewed line-by-line by the human
PR author, who stands by it.
- [x] Video or media evidence is provided for any visual changes
(optional). <!-- PR is more likely to be merged if evidence is provided
for changes made -->

## ✅ Merge Checklist

- [x] I have read the [contributor
guidelines](https://github.com/marimo-team/marimo/blob/main/CONTRIBUTING.md).
- [x] Documentation has been updated where applicable, including
docstrings for API changes.
- [x] Tests have been added for the changes made.

Author: Light2Dark

frontend/src/plugins/impl/TabsPlugin.tsx

@@ -7,6 +7,7 @@ import {
   TabsList,
   TabsTrigger,
 } from "../../components/ui/tabs";
+import { cn } from "../../utils/cn";
 import { renderHTML } from "../core/RenderHTML";
 import type { IPlugin, IPluginProps } from "../types";
 import { Labeled } from "./common/labeled";
@@ -17,6 +18,7 @@ interface Data {
    */
   tabs: string[];
   label: string | null;
+  orientation: "horizontal" | "vertical";
 }
 
 // Selected tab index
@@ -28,6 +30,7 @@ export class TabsPlugin implements IPlugin<T, Data> {
   validator = z.object({
     tabs: z.array(z.string()),
     label: z.string().nullable(),
+    orientation: z.enum(["horizontal", "vertical"]).default("horizontal"),
   });
 
   render(props: IPluginProps<T, Data>): JSX.Element {
@@ -51,6 +54,7 @@ interface TabComponentProps extends Data {
 const TabComponent = ({
   tabs,
   label,
+  orientation,
   value,
   setValue,
   children,
@@ -70,19 +74,43 @@ const TabComponent = ({
     setInternalValue(value);
   }
 
+  const isVertical = orientation === "vertical";
+  const childArray =
+    children == null ? [] : Array.isArray(children) ? children : [children];
+
   return (
-    <Labeled label={label} align="top">
-      <Tabs value={internalValue} onValueChange={handleChange}>
-        <TabsList>
+    <Labeled label={label} align="top" fullWidth={true}>
+      <Tabs
+        value={internalValue}
+        onValueChange={handleChange}
+        orientation={orientation}
+        className={cn(isVertical && "flex flex-row gap-3")}
+      >
+        <TabsList
+          className={cn(
+            "scrollbar-thin",
+            isVertical
+              ? "flex flex-col items-stretch justify-start h-auto max-h-none shrink-0 min-w-[10rem] overflow-y-auto"
+              : "max-w-full overflow-x-auto justify-start",
+          )}
+        >
           {tabs.map((tab, index) => (
-            <TabsTrigger key={index} value={index.toString()}>
+            <TabsTrigger
+              key={index}
+              value={index.toString()}
+              className={cn(isVertical && "w-full justify-start")}
+            >
               {renderHTML({ html: tab })}
             </TabsTrigger>
           ))}
         </TabsList>
-        {React.Children.map(children, (child, index) => {
-          return <TabsContent value={index.toString()}>{child}</TabsContent>;
-        })}
+        <div className={cn(isVertical && "flex-1 min-w-0")}>
+          {childArray.map((child, index) => (
+            <TabsContent key={index} value={index.toString()}>
+              {child}
+            </TabsContent>
+          ))}
+        </div>
       </Tabs>
     </Labeled>
   );

frontend/src/plugins/impl/__tests__/TabsPlugin.test.tsx

@@ -0,0 +1,154 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { fireEvent, render, screen } from "@testing-library/react";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import type { z } from "zod";
+import { initialModeAtom } from "@/core/mode";
+import { store } from "@/core/state/jotai";
+import type { IPluginProps } from "../../types";
+import { TabsPlugin } from "../TabsPlugin";
+
+describe("TabsPlugin", () => {
+  beforeAll(() => {
+    store.set(initialModeAtom, "edit");
+  });
+
+  const renderPlugin = (
+    data: z.input<TabsPlugin["validator"]>,
+    initialValue = "0",
+  ) => {
+    const plugin = new TabsPlugin();
+    const host = document.createElement("div");
+    const setValue = vi.fn();
+    const children = [
+      <span key="0">Content 0</span>,
+      <span key="1">Content 1</span>,
+      <span key="2">Content 2</span>,
+    ];
+    const makeProps = (
+      value: string,
+    ): IPluginProps<string, z.infer<TabsPlugin["validator"]>> => ({
+      data: plugin.validator.parse(data),
+      value,
+      setValue,
+      host,
+      functions: {},
+      children,
+    });
+    const result = render(plugin.render(makeProps(initialValue)));
+    return {
+      ...result,
+      setValue,
+      rerenderWithValue: (newValue: string) =>
+        result.rerender(plugin.render(makeProps(newValue))),
+    };
+  };
+
+  it("renders all tab triggers", () => {
+    renderPlugin({
+      tabs: ["First", "Second", "Third"],
+      label: null,
+    });
+    expect(screen.getByRole("tab", { name: "First" })).toBeInTheDocument();
+    expect(screen.getByRole("tab", { name: "Second" })).toBeInTheDocument();
+    expect(screen.getByRole("tab", { name: "Third" })).toBeInTheDocument();
+  });
+
+  it("supports vertical orientation", () => {
+    renderPlugin({
+      tabs: ["First", "Second"],
+      label: null,
+      orientation: "vertical",
+    });
+    const tablist = screen.getByRole("tablist");
+    expect(tablist).toHaveAttribute("data-orientation", "vertical");
+    expect(tablist.className).toMatch(/flex-col/);
+    // Horizontal scroll classes should not be applied in vertical mode.
+    expect(tablist.className).not.toMatch(/overflow-x-auto/);
+  });
+
+  it("falls back to horizontal when orientation is omitted (back-compat)", () => {
+    // Older Python kernels won't send `orientation` — make sure the validator
+    // defaults it so the frontend keeps working.
+    const plugin = new TabsPlugin();
+    const parsed = plugin.validator.parse({
+      tabs: ["First"],
+      label: null,
+    });
+    expect(parsed.orientation).toBe("horizontal");
+  });
+
+  it("selects the tab matching the initial value", () => {
+    renderPlugin({ tabs: ["First", "Second", "Third"], label: null }, "1");
+    const tabs = screen.getAllByRole("tab");
+    expect(tabs[0]).toHaveAttribute("data-state", "inactive");
+    expect(tabs[1]).toHaveAttribute("data-state", "active");
+    expect(tabs[2]).toHaveAttribute("data-state", "inactive");
+  });
+
+  it("defaults to the first tab when value is empty", () => {
+    renderPlugin({ tabs: ["First", "Second"], label: null }, "");
+    const tabs = screen.getAllByRole("tab");
+    expect(tabs[0]).toHaveAttribute("data-state", "active");
+    expect(tabs[1]).toHaveAttribute("data-state", "inactive");
+  });
+
+  it("calls setValue with the clicked tab's index", () => {
+    const { setValue } = renderPlugin({
+      tabs: ["First", "Second", "Third"],
+      label: null,
+    });
+    // Radix Tabs' trigger reacts to mousedown (left button), not click —
+    // see https://github.com/radix-ui/primitives/blob/main/packages/react/tabs/src/Tabs.tsx
+    fireEvent.mouseDown(screen.getByRole("tab", { name: "Third" }), {
+      button: 0,
+    });
+    expect(setValue).toHaveBeenCalledWith("2");
+  });
+
+  it("syncs selection when value is updated externally", () => {
+    const { rerenderWithValue } = renderPlugin(
+      { tabs: ["First", "Second", "Third"], label: null },
+      "0",
+    );
+    expect(screen.getAllByRole("tab")[0]).toHaveAttribute(
+      "data-state",
+      "active",
+    );
+
+    rerenderWithValue("2");
+    const tabs = screen.getAllByRole("tab");
+    expect(tabs[0]).toHaveAttribute("data-state", "inactive");
+    expect(tabs[2]).toHaveAttribute("data-state", "active");
+  });
+
+  it("renders HTML in tab labels via renderHTML", () => {
+    renderPlugin({
+      tabs: ["<strong>Bold</strong>", "Plain"],
+      label: null,
+    });
+    const boldTab = screen.getByRole("tab", { name: "Bold" });
+    // The label markup is preserved (not escaped as text), so the trigger
+    // contains a real <strong> element.
+    expect(boldTab.querySelector("strong")).not.toBeNull();
+  });
+
+  it("renders no tabpanels when tabs and children are empty", () => {
+    // When the Python side passes `tabs={}`, slotted HTML is empty and the
+    // resulting React children are null/undefined. We should render zero
+    // `TabsContent`s — not a stray one paired to a non-existent trigger.
+    const plugin = new TabsPlugin();
+    const host = document.createElement("div");
+    const props: IPluginProps<string, z.infer<TabsPlugin["validator"]>> = {
+      data: plugin.validator.parse({ tabs: [], label: null }),
+      value: "",
+      setValue: vi.fn(),
+      host,
+      functions: {},
+      children: null,
+    };
+    render(plugin.render(props));
+    expect(screen.queryAllByRole("tab")).toHaveLength(0);
+    expect(screen.queryAllByRole("tabpanel")).toHaveLength(0);
+  });
+});

marimo/_plugins/ui/_impl/tabs.py

@@ -1,7 +1,7 @@
 # Copyright 2026 Marimo. All rights reserved.
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Final
+from typing import TYPE_CHECKING, Final, Literal
 
 from marimo._output.formatting import as_html
 from marimo._output.md import md
@@ -41,6 +41,14 @@ class tabs(UIElement[str, str]):
         )
         ```
 
+        Stack tabs vertically (useful when there are many tabs or long labels):
+        ```python
+        tabs = mo.ui.tabs(
+            {f"Section {i}": f"Content {i}" for i in range(20)},
+            orientation="vertical",
+        )
+        ```
+
     Attributes:
         value (str): The name of the selected tab.
 
@@ -51,6 +59,8 @@ class tabs(UIElement[str, str]):
         lazy (bool, optional): Whether to lazily load the tab content.
             This is a convenience that wraps each tab in a `mo.lazy`
             component. Defaults to False.
+        orientation ("horizontal" | "vertical", optional): The orientation of
+            the tab bar. Use "vertical" to stack the tabs in a side panel. Defaults to "horizontal".
         label (str, optional): A descriptive name for the tab. Defaults to "".
         on_change (Callable[[dict[str, object]], None], optional): Optional callback
             to run when this element's value changes.
@@ -64,6 +74,7 @@ def __init__(
         value: str | None = None,
         lazy: bool = False,
         *,
+        orientation: Literal["horizontal", "vertical"] = "horizontal",
         label: str = "",
         on_change: Callable[[str], None] | None = None,
     ) -> None:
@@ -94,7 +105,7 @@ def render_content(tab: object) -> str:
             component_name=self._name,
             initial_value=index or "",
             label=label,
-            args={"tabs": tab_labels},
+            args={"tabs": tab_labels, "orientation": orientation},
             on_change=on_change,
             slotted_html=tab_items,
         )