PlTabs

One set of panels, one of which is shown. The indicator slides from the tab you left to the one you chose.

React

import { PlTab, PlTabPanel, PlTabs } from 'plass-ui';

<PlTabs defaultValue="account">
  <PlTab value="account">Account</PlTab>
  <PlTab value="billing">Billing</PlTab>

  <PlTabPanel value="account">Your name and your avatar.</PlTabPanel>
  <PlTabPanel value="billing">Cards and invoices.</PlTabPanel>
</PlTabs>;

The tabs and the panels are written as siblings and sorted apart by the component. There is no <PlTabList> to remember, and no array-of-subtrees prop. A panel is a subtree, and there is no useful shape for that which is not just children.

import 'package:plass_ui/plass_ui.dart';

PlTabs<String>(
  value: tab,
  onChanged: (String next) => setState(() => tab = next),
  tabs: <PlTab<String>>[
    PlTab<String>(
      value: 'account',
      label: const Text('Account'),
      panel: const Text('Your name and your avatar.'),
    ),
    PlTab<String>(
      value: 'billing',
      label: const Text('Billing'),
      panel: const Text('Cards and invoices.'),
    ),
  ],
);

A tab and the panel it opens are one description, which is the whole of the difference: there is no PlTabPanel to keep in step, no third value to match up, and a panel that is not chosen is never built.

Props

Prop	Type	Default	Description
variantshared	'solid' | 'glass' | 'ghost'	'glass'	What the tab **bar** is made of. solid rides a clear pane in a groove, glass runs the indicator along a rule at the edge, ghost drops the rule
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Tab height and type scale — the same ladder as PlButton
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. Arbitrary colour values are not accepted
densityshared	'default' | 'compact'	'default'	Padding only — never the height, never the type scale
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. 0 means no shadow at all
orientationshared	PlassResponsive<'horizontal' | 'vertical'>	'horizontal'	Which way the bar runs. vertical puts the tabs down the side and moves the arrow keys onto the other axis
value	string | number | null	—	The chosen tab. Use with onValueChange for a controlled set
defaultValue	string | number | null	—	Which starts chosen
onValueChange	(value: string | number | null) => void	—	Called with the new value
activateOnFocus	boolean	false	Whether the arrow keys also choose the tab they land on. Off by default — the moment one panel fetches, walking past four tabs fires four requests
loopFocus	boolean	true	Whether the arrow keys wrap from the last tab back to the first
fullWidth	boolean	false	The tabs share the bar's full width, each taking an equal part of it
wheel	boolean	true	Turns a vertical wheel over a bar with more tabs than room into travel along it. A bar whose tabs all fit is left alone
overscrollshared	'auto' | 'contain'	'contain'	What the bar does with a wheel it has run out of tabs for. contain keeps it, auto hands it to the page
children	ReactNode	—	The PlTab and PlTabPanel children. The component sorts the two apart itself

Prop	Type	Default	Description
tabs *	List<PlTab<T>>	—	The tabs, as a list of descriptions rather than children, each carrying its own panel
value *	T?	—	The chosen tab. null is a bar with nothing chosen
onChanged	ValueChanged<T>?	—	Called with the new value
variantshared	PlassVariant	PlassVariant.glass	What the tab **bar** is made of. solid rides a clear pane in a groove, glass runs the indicator along a rule at the edge, ghost drops the rule
sizeshared	PlassSize	PlassSize.md	Tab height and type scale — the same ladder as PlButton
colorshared	PlassColor	PlassColor.primary	Semantic colour role. Arbitrary colour values are not accepted
densityshared	PlassDensity	PlassDensity.standard	Padding only — never the height, never the type scale
orientationshared	PlassResponsive<PlassOrientation>	PlassOrientation.horizontal	Which way the bar runs. vertical puts the tabs down the side and moves the arrow keys onto the other axis
fullWidth	bool	false	The tabs share the bar's full width, each taking an equal part of it
wheel	bool	true	Turns a vertical wheel over a bar with more tabs than room into travel along it. A bar whose tabs all fit is left alone
overscrollshared	PlassOverscroll	PlassOverscroll.contain	What the bar does with a wheel it has run out of tabs for. contain keeps it, auto hands it to whatever is behind the bar
semanticLabel	String?	—	The name a screen reader gives the bar. It has no visible label of its own
focusNode	FocusNode?	—	Drives the bar's one focus stop from outside
autofocus	bool	false	Takes focus as it is inserted into the tree

The bar and the panels take a value of string | number.

The bar is generic in its tab's type (PlTabs<String>, PlTabs<Section>), so value and onChanged are typed rather than dynamic, and it is controlled, like every other control in the package. value is nullable: null is a bar with nothing chosen and no panel under it.

PlTab

Prop	Type	Default	Description
value *	string | number	—	Identifies the tab, and picks out the panel with the same value
startIcon	ReactNode	—	Content before the label. Sized in em, so it tracks the label
endIcon	ReactNode	—	Content after the label — a count, a status dot
disabled	boolean	false	Unavailable, but still listed
children	ReactNode	—	The tab's label

Prop	Type	Default	Description
value *	T	—	Identifies the tab, and picks out the panel with the same value
label	Widget?	—	The tab's label
startIcon	Widget?	—	Content before the label, drawn at 1.2× it so it tracks the label's size
endIcon	Widget?	—	Content after the label — a count, a status dot
disabled	bool	false	Unavailable, but still listed
panel	Widget?	—	What is shown under the bar when this tab is chosen. Only the chosen panel is built

PlTabPanel

Prop	Type	Default	Description
value *	string | number	—	Which tab shows this panel
keepMounted	boolean	false	Keeps the panel in the DOM while it is hidden. For one that is expensive to build, or that holds form state
children	ReactNode	—	The panel's content

PlTabPanel is not in the Flutter package yet.

variant, size, density and orientation are read from the PlTabs around them. A tab that could disagree with its neighbours about any of those is a tab bar with a hole in it.

A tab is a PlTab, a description rather than a widget, for the reason a segment is one: the bar owns the roving focus, the arrow keys and the indicator that slides between the tabs, so it has to know which one is chosen and where each one is. Its panel rides along, because a tab and what it opens are the same fact written twice otherwise.

It carries no variant, no size, no density and no orientation, and could not. A tab that disagrees with its neighbours about any of those is a tab bar with a hole in it.

What the shared axes (variant size color density orientation) mean across the library is in prop conventions.

Tabs or a segmented button

Tabs swap whole panels of content. A segmented button filters what is already on screen. That is also why the solid tile here is a pane of clear glass rather than the family's gradient. The gradient tile belongs to the segmented button, and a screen with both should be able to tell them apart.

Examples

variant

glass is the classic bar: a rule along its edge with the indicator riding on it. solid is a groove with a pane sliding in it. ghost is the same bar with the rule taken away, for tabs inside a PlCard that already has an edge of its own.

React

import { PlTab, PlTabPanel, PlTabs } from 'plass-ui';

export default function TabsVariants() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-6">
      {(['solid', 'glass', 'ghost'] as const).map((variant) => (
        <PlTabs key={variant} variant={variant} size="sm" defaultValue="one">
          <PlTab value="one">First</PlTab>
          <PlTab value="two">Second</PlTab>
          <PlTab value="three">Third</PlTab>

          <PlTabPanel value="one">The bar is {variant}.</PlTabPanel>
          <PlTabPanel value="two">Still {variant}.</PlTabPanel>
          <PlTabPanel value="three">And still {variant}.</PlTabPanel>
        </PlTabs>
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TabsVariants extends StatelessWidget {
  const TabsVariants({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 512,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        mainAxisSize: MainAxisSize.min,
        spacing: 24,
        children: <Widget>[
          for (final variant in PlassVariant.values)
            PlTabs<String>(
              variant: variant,
              size: PlassSize.sm,
              value: 'one',
              onChanged: (String next) {},
              tabs: <PlTab<String>>[
                PlTab<String>(
                  value: 'one',
                  label: const Text('First'),
                  panel: Text('The bar is ${variant.name}.'),
                ),
                const PlTab<String>(value: 'two', label: Text('Second')),
                const PlTab<String>(value: 'three', label: Text('Third')),
              ],
            ),
        ],
      ),
    );
  }
}

orientation

vertical puts the tabs down the side and the panel beside them, and moves the arrow keys onto the other axis, which is Base UI's doingwhich the bar does itself, and is what makes a vertical tab bar reachable.

It is responsive, so a set can run one way on a phone and the other on a laptop. A server renders the xs entry and the browser corrects it on hydration.It is resolved against the window's width during build, so the first frame is already right. See breakpoints.

React

import { PlTab, PlTabPanel, PlTabs } from 'plass-ui';

export default function TabsOrientation() {
  return (
    <PlTabs orientation="vertical" defaultValue="general" className="w-full max-w-lg">
      <PlTab value="general">General</PlTab>
      <PlTab value="security">Security</PlTab>
      <PlTab value="webhooks">Webhooks</PlTab>

      <PlTabPanel value="general">The name of the project and who owns it.</PlTabPanel>
      <PlTabPanel value="security">Two-factor authentication and session alerts.</PlTabPanel>
      <PlTabPanel value="webhooks">Point a URL at an event and we will POST to it.</PlTabPanel>
    </PlTabs>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TabsOrientation extends StatefulWidget {
  const TabsOrientation({super.key});

  @override
  State<TabsOrientation> createState() => _TabsOrientationState();
}

class _TabsOrientationState extends State<TabsOrientation> {
  String _tab = 'general';

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 512,
      child: PlTabs<String>(
        orientation: const PlassResponsive<PlassOrientation>(PlassOrientation.vertical),
        value: _tab,
        onChanged: (String next) => setState(() => _tab = next),
        tabs: const <PlTab<String>>[
          PlTab<String>(
            value: 'general',
            label: Text('General'),
            panel: Text('The name of the project and who owns it.'),
          ),
          PlTab<String>(
            value: 'security',
            label: Text('Security'),
            panel: Text('Two-factor authentication and session alerts.'),
          ),
          PlTab<String>(
            value: 'webhooks',
            label: Text('Webhooks'),
            panel: Text('Point a URL at an event and we will POST to it.'),
          ),
        ],
      ),
    );
  }
}

fullWidth

React

import { PlTab, PlTabPanel, PlTabs } from 'plass-ui';

export default function TabsFullWidth() {
  return (
    <PlTabs fullWidth variant="solid" defaultValue="open" className="w-full max-w-lg">
      <PlTab value="open">Open</PlTab>
      <PlTab value="paid">Paid</PlTab>
      <PlTab value="void">Void</PlTab>

      <PlTabPanel value="open">Three invoices are waiting.</PlTabPanel>
      <PlTabPanel value="paid">Everything else has cleared.</PlTabPanel>
      <PlTabPanel value="void">Nothing has been voided this year.</PlTabPanel>
    </PlTabs>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TabsFullWidth extends StatefulWidget {
  const TabsFullWidth({super.key});

  @override
  State<TabsFullWidth> createState() => _TabsFullWidthState();
}

class _TabsFullWidthState extends State<TabsFullWidth> {
  String _tab = 'open';

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 512,
      child: PlTabs<String>(
        fullWidth: true,
        variant: PlassVariant.solid,
        value: _tab,
        onChanged: (String next) => setState(() => _tab = next),
        tabs: const <PlTab<String>>[
          PlTab<String>(
            value: 'open',
            label: Text('Open'),
            panel: Text('Three invoices are waiting.'),
          ),
          PlTab<String>(
            value: 'paid',
            label: Text('Paid'),
            panel: Text('Everything else has cleared.'),
          ),
          PlTab<String>(
            value: 'void',
            label: Text('Void'),
            panel: Text('Nothing has been voided this year.'),
          ),
        ],
      ),
    );
  }
}

size

A tab is a control, so it takes the control height ladder. A md tab and a md PlButton are the same 40px, which is what lets a tab bar sit in a toolbar next to one without the row losing its baseline.

React

import { PlTab, PlTabPanel, PlTabs } from 'plass-ui';

export default function TabsSizes() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-6">
      {(['sm', 'md', 'lg'] as const).map((size) => (
        <PlTabs key={size} size={size} defaultValue="one">
          <PlTab value="one">{`size="${size}"`}</PlTab>
          <PlTab value="two">Second</PlTab>

          <PlTabPanel value="one">The tabs take the control height ladder.</PlTabPanel>
          <PlTabPanel value="two">So a tab bar lines up with a button beside it.</PlTabPanel>
        </PlTabs>
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TabsSizes extends StatelessWidget {
  const TabsSizes({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 512,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        mainAxisSize: MainAxisSize.min,
        spacing: 24,
        children: <Widget>[
          for (final size in <PlassSize>[PlassSize.sm, PlassSize.md, PlassSize.lg])
            PlTabs<String>(
              size: size,
              value: 'one',
              onChanged: (String next) {},
              tabs: <PlTab<String>>[
                PlTab<String>(
                  value: 'one',
                  label: Text('size: ${size.name}'),
                  panel: const Text('The tabs take the control height ladder.'),
                ),
                const PlTab<String>(
                  value: 'two',
                  label: Text('Second'),
                  panel: Text('So a tab bar lines up with a button beside it.'),
                ),
              ],
            ),
        ],
      ),
    );
  }
}

A bar with more tabs than room

A bar with more tabs than room scrolls rather than wrapping: a tab bar on two lines has stopped being a bar, and the indicator has nowhere sensible to sit.

Which is why the bar has to say it is scrolling, and a scrollbar does not. On a Mac it is an overlay that appears only while the strip is moving, and a reader decides whether there is more to look at the rest of the time. On Windows the same bar is fifteen pixels of permanent furniture under a row of labels. Both are taken away, and the end that still has tabs behind it is faded out instead. Only that end, so a faded edge always means there is more.

The fade takes the pixels away rather than painting over them, so it is right whatever the bar is sitting on. A component cannot know whether it is on the page, on a PlCard or on a tinted section, and a gradient painted in the wrong colour would be worse than no signal at all. It is dropped while a tab inside is showing a focus ring, because focusing a tab scrolls it flush against the edge the fade is strongest at.

Whether a bar overflows depends on the room it was given, so this is measured rather than declared. There is no prop for it.

The state is published as data-overflow on the tab list. none, start, end or both, in the reader's order, so a page can style against it or assert on it.

React

import { PlTab, PlTabPanel, PlTabs } from 'plass-ui';

const regions = [
  { value: 'seoul', label: 'Seoul', panel: 'Nine racks, all of them warm.' },
  { value: 'tokyo', label: 'Tokyo', panel: 'Two racks, one of them new.' },
  { value: 'sydney', label: 'Sydney', panel: 'A single rack, and a quiet week.' },
  { value: 'mumbai', label: 'Mumbai', panel: 'Four racks, and the busiest queue.' },
  { value: 'frankfurt', label: 'Frankfurt', panel: 'Six racks, and a spare.' },
  { value: 'dublin', label: 'Dublin', panel: 'Three racks, one being replaced.' },
  { value: 'saopaulo', label: 'São Paulo', panel: 'Two racks, both new this month.' },
  { value: 'virginia', label: 'N. Virginia', panel: 'Twelve racks, and the oldest of them.' }
];

export default function TabsOverflow() {
  return (
    <PlTabs defaultValue="seoul" className="w-full max-w-md">
      {regions.map((region) => (
        <PlTab key={region.value} value={region.value}>
          {region.label}
        </PlTab>
      ))}

      {regions.map((region) => (
        <PlTabPanel key={region.value} value={region.value}>
          {region.panel}
        </PlTabPanel>
      ))}
    </PlTabs>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TabsOverflow extends StatefulWidget {
  const TabsOverflow({super.key});

  @override
  State<TabsOverflow> createState() => _TabsOverflowState();
}

class _TabsOverflowState extends State<TabsOverflow> {
  String _tab = 'seoul';

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 448,
      child: PlTabs<String>(
        value: _tab,
        onChanged: (String next) => setState(() => _tab = next),
        tabs: const <PlTab<String>>[
          PlTab<String>(
            value: 'seoul',
            label: Text('Seoul'),
            panel: Text('Nine racks, all of them warm.'),
          ),
          PlTab<String>(
            value: 'tokyo',
            label: Text('Tokyo'),
            panel: Text('Two racks, one of them new.'),
          ),
          PlTab<String>(
            value: 'sydney',
            label: Text('Sydney'),
            panel: Text('A single rack, and a quiet week.'),
          ),
          PlTab<String>(
            value: 'mumbai',
            label: Text('Mumbai'),
            panel: Text('Four racks, and the busiest queue.'),
          ),
          PlTab<String>(
            value: 'frankfurt',
            label: Text('Frankfurt'),
            panel: Text('Six racks, and a spare.'),
          ),
          PlTab<String>(
            value: 'dublin',
            label: Text('Dublin'),
            panel: Text('Three racks, one being replaced.'),
          ),
          PlTab<String>(
            value: 'saopaulo',
            label: Text('São Paulo'),
            panel: Text('Two racks, both new this month.'),
          ),
          PlTab<String>(
            value: 'virginia',
            label: Text('N. Virginia'),
            panel: Text('Twelve racks, and the oldest of them.'),
          ),
        ],
      ),
    );
  }
}

A bar that scrolls answers the wheel. A mouse has one wheel and it points down the page, which is the one direction the bar does not run in, so a vertical wheel over an overflowing bar moves it along instead — the reader who can see there are more tabs has a way of reaching them that is neither the scrollbar the bar deliberately does not draw nor the arrow keys, which also change the selection. wheel turns that off, and a bar whose tabs all fit never takes the gesture at all.

overscroll decides what happens after the last tab. contain, the default, keeps the wheel on the bar, so working along a long row does not end with the page moving under the reader. auto hands it back at the ends, holding only the gesture that was already moving the bar.

<PlTabs wheel={false} overscroll="auto">

PlTabs<String>(wheel: false, overscroll: PlassOverscroll.auto, tabs: tabs);

Controlled

React

import { useState } from 'react';
import { PlButton, PlTab, PlTabPanel, PlTabs } from 'plass-ui';

export default function TabsControlled() {
  const [tab, setTab] = useState<string | number | null>('write');

  return (
    <div className="flex w-full max-w-lg flex-col gap-3">
      <PlTabs value={tab} onValueChange={setTab}>
        <PlTab value="write">Write</PlTab>
        <PlTab value="preview">Preview</PlTab>

        <PlTabPanel value="write">Markdown goes in here.</PlTabPanel>
        <PlTabPanel value="preview">And comes out rendered here.</PlTabPanel>
      </PlTabs>

      <PlButton
        size="sm"
        variant="glass"
        color="secondary"
        onClick={() => setTab(tab === 'write' ? 'preview' : 'write')}
      >
        Toggle from outside
      </PlButton>
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TabsControlled extends StatefulWidget {
  const TabsControlled({super.key});

  @override
  State<TabsControlled> createState() => _TabsControlledState();
}

class _TabsControlledState extends State<TabsControlled> {
  String _tab = 'write';

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 512,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        mainAxisSize: MainAxisSize.min,
        spacing: 12,
        children: <Widget>[
          PlTabs<String>(
            value: _tab,
            onChanged: (String next) => setState(() => _tab = next),
            tabs: const <PlTab<String>>[
              PlTab<String>(
                value: 'write',
                label: Text('Write'),
                panel: Text('Markdown goes in here.'),
              ),
              PlTab<String>(
                value: 'preview',
                label: Text('Preview'),
                panel: Text('And comes out rendered here.'),
              ),
            ],
          ),
          PlButton(
            size: PlassSize.sm,
            variant: PlassVariant.glass,
            color: PlassColor.secondary,
            onPressed: () => setState(() => _tab = _tab == 'write' ? 'preview' : 'write'),
            child: const Text('Toggle from outside'),
          ),
        ],
      ),
    );
  }
}

Accessibility

• Base UI owns everything that makes a tab bar a tab bar rather than a row of buttons: roving focus so the whole bar is one tab stop, the arrow keys on whichever axis it runs, Home and End, the tab / tabpanel roles, and the aria-controls wiring between them.
• activateOnFocus is off by default. Automatic activation is only kind when every panel is already on the page; the moment one of them fetches, walking past four tabs fires four requests.
• A panel with nothing focusable inside takes focus itself, so its content is reachable from the keyboard.
• The focus ring on a tab is drawn inset, because an offset ring on a tab inside a solid groove would be painted over its neighbours.
• The indicator animates left, top, width and height rather than a transform. It is an empty box: nothing with text in it moves.
• A bar with more tabs than room scrolls rather than wrapping, and fades the end that still has tabs behind it. A tab bar on two lines has stopped being a bar, and the indicator has nowhere sensible to sit.

• One focus stop for the whole bar: exactly one tab is in the tab order and the rest are wrapped in an ExcludeFocus. That is what makes a bar a bar rather than a row of buttons.
• ← → on a horizontal bar and ↑ ↓ on a vertical one move the choice, wrapping at both ends and stepping over a disabled tab. Enter and Space choose the focused one.
• Each tab is announced as one of a mutually exclusive set, chosen or not, and the bar is a container you can give a semanticLabel. Give it one. A bar has no visible label of its own.
• Moving the focus moves the choice, because only the chosen panel is built and a bar that let focus and content disagree would be showing one thing and reading another. If a panel is expensive, keep the work out of build rather than out of the tab.
• A tab's focus ring turns inward, because a ring drawn outside a tab in a solid groove would be painted over its neighbours.
• The indicator animates its box, position and size, rather than a transform. It is an empty rectangle: nothing with text in it moves. With animations turned off at the OS it jumps.
• A bar with more tabs than room scrolls rather than wrapping, and fades the end that still has tabs behind it. It used to be as wide as its tabs and overflow its box, and the advice was to wrap it yourself, which does not work: a SingleChildScrollView around a PlTabs scrolls the panel with the bar.

Differences from the React build

React	Flutter	Why
<PlTab> and <PlTabPanel> children	tabs, as descriptions, each carrying its panel	The bar owns the roving focus, the arrow keys and the sliding indicator, so it has to know which tab is chosen and where each one is. Pairing the panel with its tab removes the third place the value had to match.
defaultValue / onValueChange	value / onChanged	Flutter's own controls are controlled, and its name for the callback.
a value of string | number	a generic T	Dart has generics, so the type is checked rather than restrained by convention.
every panel rendered, one shown	only the chosen panel built	A tab that is not open costs nothing. It also means a panel loses its state when you leave it, hold that state above the bar.
activateOnFocus	—	Moving focus moves the choice, always, because the panel is built from the choice.
aria-label	semanticLabel	Flutter's name.
the tab / tabpanel roles, aria-controls	a mutually exclusive selected node, and one panel	Flutter names the state on the node itself; there is no id to point at.
className, style	—	There is no class list and no style attribute to pass through.