@viraui/react 2026.9.1 → 2026.10.0

package/dist/catalog.json

@@ -302,6 +302,12 @@
       "summary": "Toolbar toggle set with shared selection state; Stack direction follows orientation with zero default gap.",
       "agentDocs": "./specs/components/toggle-group/meta.xml"
     },
+    {
+      "id": "toggle-text-button",
+      "name": "ToggleTextButton",
+      "summary": "Labeled two-state toggle on Base UI Toggle with Button chrome; visible text children, optional addon / pressedVariant; no resting/pressed icon pair.",
+      "agentDocs": "./specs/components/toggle-text-button/meta.xml"
+    },
     {
       "id": "typewriter",
       "name": "Typewriter",

package/dist/components/index.d.ts

@@ -48,5 +48,6 @@ export * from './title';
 export * from './toast';
 export * from './toggle-button';
 export * from './toggle-group';
+export * from './toggle-text-button';
 export * from './typewriter';
 export * from './tooltip';

package/dist/components/tabs/tabs-list.js

@@ -3,31 +3,37 @@ import { Stack } from "../stack/stack.js";
 import { Surface } from "../surface/surface.js";
 import tabs_module_default from "./tabs.module.js";
 import { TabsIndicator } from "./tabs-indicator.js";
+import { useTabsSize } from "./tabs-size-context.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Tabs } from "@base-ui/react/tabs";
 //#region src/components/tabs/tabs-list.tsx
-var TabsList = ({ children, className, activateOnFocus = true, ref, ...otherProps }) => /* @__PURE__ */ jsxs(Tabs.List, {
-	className: clsx(tabs_module_default.List, className),
-	activateOnFocus,
-	render: /* @__PURE__ */ jsx(Surface, {
-		color: 1,
-		border: "all",
-		radius: "m",
-		vPadding: "2xs"
-	}),
-	ref,
-	...otherProps,
-	children: [/* @__PURE__ */ jsx(TabsIndicator, {}), /* @__PURE__ */ jsx("div", {
-		className: tabs_module_default.Track,
-		children: /* @__PURE__ */ jsx(Stack, {
-			expandChildren: true,
-			fullWidth: true,
-			direction: "row",
-			hAlign: "start",
-			vAlign: "center",
-			children
-		})
-	})]
-});
+var TabsList = ({ children, className, activateOnFocus = true, ref, ...otherProps }) => {
+	const size = useTabsSize();
+	const listRadius = size === "s" ? "s" : "m";
+	return /* @__PURE__ */ jsxs(Tabs.List, {
+		className: clsx(tabs_module_default.List, className),
+		activateOnFocus,
+		"data-size": size,
+		render: /* @__PURE__ */ jsx(Surface, {
+			color: 1,
+			border: "all",
+			radius: listRadius,
+			vPadding: "2xs"
+		}),
+		ref,
+		...otherProps,
+		children: [/* @__PURE__ */ jsx(TabsIndicator, {}), /* @__PURE__ */ jsx("div", {
+			className: tabs_module_default.Track,
+			children: /* @__PURE__ */ jsx(Stack, {
+				expandChildren: true,
+				fullWidth: true,
+				direction: "row",
+				hAlign: "start",
+				vAlign: "center",
+				children
+			})
+		})]
+	});
+};
 //#endregion
 export { TabsList };

package/dist/components/tabs/tabs-size-context.d.ts

@@ -0,0 +1,4 @@
+import { ButtonProps } from '../button/button';
+export type TabsSize = NonNullable<ButtonProps['size']>;
+export declare const TabsSizeContext: import('react').Context<TabsSize>;
+export declare const useTabsSize: () => TabsSize;

package/dist/components/tabs/tabs-size-context.js

@@ -0,0 +1,7 @@
+"use client";
+import { createContext, useContext } from "react";
+//#region src/components/tabs/tabs-size-context.ts
+var TabsSizeContext = createContext("m");
+var useTabsSize = () => useContext(TabsSizeContext);
+//#endregion
+export { TabsSizeContext, useTabsSize };

package/dist/components/tabs/tabs-tab.js

@@ -2,24 +2,29 @@ import { clsx } from "../../core/clsx.js";
 import { Text } from "../text/text.js";
 import { Button } from "../button/button.js";
 import tabs_module_default from "./tabs.module.js";
+import { useTabsSize } from "./tabs-size-context.js";
 import { jsx } from "react/jsx-runtime";
 import { Tabs } from "@base-ui/react/tabs";
 //#region src/components/tabs/tabs-tab.tsx
-var TabsTab = ({ addon, addonPosition = "start", children, className, ...otherProps }) => /* @__PURE__ */ jsx(Tabs.Tab, {
-	render: /* @__PURE__ */ jsx(Button, {
-		variant: "flat",
-		addon,
-		addonPosition,
-		className: clsx(tabs_module_default.Item, className)
-	}),
-	...otherProps,
-	children: /* @__PURE__ */ jsx(Text, {
-		fluid: false,
-		tone: "muted",
-		whiteSpace: "nowrap",
-		className: tabs_module_default.Label,
-		children
-	})
-});
+var TabsTab = ({ addon, addonPosition = "start", children, className, ...otherProps }) => {
+	const size = useTabsSize();
+	return /* @__PURE__ */ jsx(Tabs.Tab, {
+		render: /* @__PURE__ */ jsx(Button, {
+			variant: "flat",
+			size,
+			addon,
+			addonPosition,
+			className: clsx(tabs_module_default.Item, className)
+		}),
+		...otherProps,
+		children: /* @__PURE__ */ jsx(Text, {
+			fluid: false,
+			tone: "muted",
+			whiteSpace: "nowrap",
+			className: tabs_module_default.Label,
+			children
+		})
+	});
+};
 //#endregion
 export { TabsTab };

package/dist/components/tabs/tabs.d.ts

@@ -1,5 +1,6 @@
 import { TabsRoot } from '@base-ui/react/tabs';
 import { StackProps } from '..';
+import { ButtonProps } from '../button/button';
 import { TabsListProps } from './tabs-list';
 import { TabsPanelProps } from './tabs-panel';
 import { TabsTabProps } from './tabs-tab';
@@ -20,6 +21,12 @@ export type TabsProps = TabsRoot.Props & {
      * @defaultValue 'start'
      */
     listAlignment?: Extract<StackProps['hAlign'], 'start' | 'center' | 'end' | 'stretch'>;
+    /**
+     * Shared visual size for tab items (`Button`) and the active indicator footprint.
+     *
+     * @defaultValue 'm'
+     */
+    size?: ButtonProps['size'];
 };
 type TabsComponent = React.FC<TabsProps> & {
     List: React.FC<TabsListProps>;

package/dist/components/tabs/tabs.js

@@ -2,6 +2,7 @@ import './tabs.css';
 import { clsx } from "../../core/clsx.js";
 import { Stack } from "../stack/stack.js";
 import tabs_module_default from "./tabs.module.js";
+import { TabsSizeContext } from "./tabs-size-context.js";
 import { TabsList } from "./tabs-list.js";
 import { TabsPanel } from "./tabs-panel.js";
 import { TabsTab } from "./tabs-tab.js";
@@ -10,14 +11,17 @@ import { jsx } from "react/jsx-runtime";
 import "react";
 import { Tabs } from "@base-ui/react/tabs";
 //#region src/components/tabs/tabs.tsx
-var TabsRootComponent = ({ children, className, listAlignment = "start", ...otherProps }) => /* @__PURE__ */ jsx(Tabs.Root, {
-	render: /* @__PURE__ */ jsx(Stack, {
-		hAlign: listAlignment,
-		vAlign: "start",
-		className: clsx(tabs_module_default.Tabs, className)
-	}),
-	...otherProps,
-	children
+var TabsRootComponent = ({ children, className, listAlignment = "start", size = "m", ...otherProps }) => /* @__PURE__ */ jsx(TabsSizeContext.Provider, {
+	value: size,
+	children: /* @__PURE__ */ jsx(Tabs.Root, {
+		render: /* @__PURE__ */ jsx(Stack, {
+			hAlign: listAlignment,
+			vAlign: "start",
+			className: clsx(tabs_module_default.Tabs, className)
+		}),
+		...otherProps,
+		children
+	})
 });
 var Tabs$1 = Object.assign(TabsRootComponent, {
 	List: TabsList,

package/dist/components/toggle-group/toggle-group.d.ts

@@ -4,7 +4,9 @@ import { ToggleGroup as ToggleGroupPrimitive } from '@base-ui/react/toggle-group
  *
  * Thin wrapper around Base UI `ToggleGroup` with default `Stack` direction
  * (`row` / `column` from `orientation`) and zero gap — consumers own spacing.
- * Compose `ToggleButton` children each with `value` and an accessible name.
+ * Compose `ToggleButton` and/or `ToggleTextButton` children each with `value`
+ * (icon-only children also need an accessible name).
+
  *
  * @defaultValue Base UI pass-through props keep upstream defaults.
  */

package/dist/components/toggle-text-button/index.d.ts

@@ -0,0 +1,2 @@
+export { ToggleTextButton } from './toggle-text-button';
+export type { ToggleTextButtonProps } from './toggle-text-button';

package/dist/components/toggle-text-button/toggle-text-button.d.ts

@@ -0,0 +1,27 @@
+import { Toggle as TogglePrimitive } from '@base-ui/react/toggle';
+import { ButtonProps } from '../button/button';
+import * as React from 'react';
+/**
+ * Public ToggleTextButton props.
+ *
+ * Labeled two-state control built on Base UI `Toggle` and `Button`.
+ * Prefer a visible text `children` label; supply `aria-label` or `aria-labelledby`
+ * when children are empty or whitespace-only.
+ *
+ * @defaultValue Base UI toggle pass-through props keep upstream defaults.
+ */
+export type ToggleTextButtonProps = Omit<ButtonProps, 'render' | 'variant'> & Omit<TogglePrimitive.Props, 'render' | 'children'> & {
+    /**
+     * Visual variant while the toggle is not pressed.
+     *
+     * @defaultValue 'flat'
+     */
+    variant?: ButtonProps['variant'];
+    /**
+     * Visual variant while the toggle is pressed.
+     *
+     * @defaultValue When omitted, `variant` is used in both states.
+     */
+    pressedVariant?: ButtonProps['variant'];
+};
+export declare const ToggleTextButton: React.FC<ToggleTextButtonProps>;

package/dist/components/toggle-text-button/toggle-text-button.js

@@ -0,0 +1,24 @@
+import { Button } from "../button/button.js";
+import { jsx } from "react/jsx-runtime";
+import "react";
+import { mergeProps } from "@base-ui/react/merge-props";
+import { Toggle } from "@base-ui/react/toggle";
+//#region src/components/toggle-text-button/toggle-text-button.tsx
+var ToggleTextButton = ({ variant = "flat", pressedVariant, pressed, defaultPressed, onPressedChange, value, disabled, ref, ...otherProps }) => /* @__PURE__ */ jsx(Toggle, {
+	ref,
+	value,
+	pressed,
+	defaultPressed,
+	onPressedChange,
+	disabled,
+	render: (toggleProps, state) => {
+		const { "aria-label": _toggleAriaLabel, "aria-labelledby": _toggleAriaLabelledBy, ...restToggleProps } = toggleProps;
+		return /* @__PURE__ */ jsx(Button, {
+			...mergeProps(restToggleProps, otherProps),
+			disabled,
+			variant: state.pressed ? pressedVariant ?? variant : variant
+		});
+	}
+});
+//#endregion
+export { ToggleTextButton };

package/dist/index.js

@@ -70,7 +70,8 @@ import { Title } from "./components/title/title.js";
 import { Toast } from "./components/toast/toast.js";
 import { ToggleButton } from "./components/toggle-button/toggle-button.js";
 import { ToggleGroup } from "./components/toggle-group/toggle-group.js";
+import { ToggleTextButton } from "./components/toggle-text-button/toggle-text-button.js";
 import { Typewriter } from "./components/typewriter/typewriter.js";
 import { TooltipContent } from "./components/tooltip/tooltip-content.js";
 import { Tooltip, TooltipProvider, TooltipTrigger } from "./components/tooltip/tooltip.js";
-export { Accordion, Annotate, Autocomplete, Avatar, AvatarGroup, Badge, Beam, Bleed, BreakpointsProvider, Button, ButtonLink, Checkbox, CheckboxGroup, Chip, ClampText, Dialog, DialogClose, DialogIndent, DialogIndentBackground, DialogSheet, DialogTrigger, DirectionProvider, Disclosure, ELEVATION_DEFAULTS, Elevator, Fieldset, FitText, Glow, Grid, IconButton, IconButtonLink, LinearProgress, Masonry, Menu, MenuCheckboxItem, MenuGroup, MenuItem, MenuLinkItem, MenuPopup, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Meter, NumberField, OTPField, Popover, PopoverClose, PopoverDescription, PopoverSheet, PopoverTitle, PopoverTrigger, ProgressiveBlur, Prose, Radio, RadioGroup, Select, Separator, Shimmer, Skeleton, Slider, Spinner, Stack, StaticNoise, Surface, Switch, Tabs, Text, Textarea, Textfield, Title, Toast, ToggleButton, ToggleGroup, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Typewriter, getElevationProps, useBreakpoints, useDirection };
+export { Accordion, Annotate, Autocomplete, Avatar, AvatarGroup, Badge, Beam, Bleed, BreakpointsProvider, Button, ButtonLink, Checkbox, CheckboxGroup, Chip, ClampText, Dialog, DialogClose, DialogIndent, DialogIndentBackground, DialogSheet, DialogTrigger, DirectionProvider, Disclosure, ELEVATION_DEFAULTS, Elevator, Fieldset, FitText, Glow, Grid, IconButton, IconButtonLink, LinearProgress, Masonry, Menu, MenuCheckboxItem, MenuGroup, MenuItem, MenuLinkItem, MenuPopup, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Meter, NumberField, OTPField, Popover, PopoverClose, PopoverDescription, PopoverSheet, PopoverTitle, PopoverTrigger, ProgressiveBlur, Prose, Radio, RadioGroup, Select, Separator, Shimmer, Skeleton, Slider, Spinner, Stack, StaticNoise, Surface, Switch, Tabs, Text, Textarea, Textfield, Title, Toast, ToggleButton, ToggleGroup, ToggleTextButton, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Typewriter, getElevationProps, useBreakpoints, useDirection };

package/dist/specs/components/icon-button/props.xml

@@ -9,7 +9,8 @@
     <item>Actions that need visible text — use Button</item>
     <item>Missing both aria-label and aria-labelledby</item>
     <item>Navigation or non-button semantics — use IconButtonLink</item>
-    <item>Temporally swap icons after user interactions with temporal pressed state, like copy feedback. Use ToggleButton instead</item>
+    <item>Temporally swap icons after user interactions with temporal pressed state, like copy feedback. Use ToggleButton (icon-only) or ToggleTextButton (labeled)</item>
+
   </when_not_to_use>
   <prop name="icon" kind="react">
     <description>Icon rendered as the sole visible control content. Omit glyph `size` / width / height — host CSS sizes SVG via `--vui-button-icon-size`.</description>

package/dist/specs/components/icon-button/usage.xml

@@ -10,7 +10,8 @@
   <do>Icon-only navigation — use IconButtonLink (framework Link via `render`)</do>
   <dont>Passing `children`, `addon`, or `addonPosition` — not part of the public API; use `icon`</dont>
   <dont>Using icon-only Button instead of IconButton</dont>
-  <dont>Using IconButton for persistent or temporal pressed state — use ToggleButton</dont>
+  <dont>Using IconButton for persistent or temporal pressed state — use ToggleButton (icon-only) or ToggleTextButton (labeled)</dont>
+
   <dont>Using IconButton with `render={&lt;a /&gt;}` for links — use IconButtonLink</dont>
   <dont>Omitting both `aria-label` and `aria-labelledby`</dont>
   <dont>Passing `size={16}` / `size=&quot;1rem&quot;` (or width/height) on the `icon` glyph — IconButton CSS sizes SVG descendants</dont>

package/dist/specs/components/tabs/props.xml

@@ -12,6 +12,9 @@
   <prop name="listAlignment" kind="react">
     <description>Horizontal alignment of tab list within root Stack.</description>
   </prop>
+  <prop name="size" kind="react">
+    <description>Shared visual size for tab items (`Button`) and the active indicator footprint. Values match `Button` size (`s` | `m` | `l`). Default `m`.</description>
+  </prop>
   <prop name="Tab.addon" kind="react">
     <description>Decorative addon rendered alongside the tab label. Omit glyph `size` / width / height unless expressly overriding the icon-library default.</description>
   </prop>

package/dist/specs/components/tabs/usage.xml

@@ -4,6 +4,7 @@
   <do>Login/signup (or similar) form swap: wrap Tabs in Surface; panels hold Stack with Textfield(s) + Button (+ optional Fieldset) — use Stack `rowGap` / `fullWidth` / `expandChildren` and Textfield `fullWidth`; invent 0 width/gap CSS</do>
   <do>Compound order: `Tabs.List` → `Tabs.Tab`(s), then `Tabs.Viewport` → `Tabs.Panel`(s) with matching `value`</do>
   <do>Fill list chrome with `listAlignment=&quot;stretch&quot;`; center/end via `listAlignment` on the root</do>
+  <do>Set shared tab + indicator scale with root `size` (`m` default; `s` / `l` match `Button`)</do>
   <do>Decorative `Tab` `addon` / `addonPosition` beside a visible text label — omit glyph `size` / width / height unless expressly overriding</do>
   <dont>Using addons as the only visible label for a tab</dont>
   <dont>Passing `size={16}` on every Tab `addon` icon by habit — prefer icon-library default</dont>

package/dist/specs/components/toggle-button/props.xml

@@ -7,9 +7,11 @@
     <item>Temporally swap icons after user interactions with temporal pressed state, like copy feedback.</item>
   </when_to_use>
   <when_not_to_use>
+    <item>Labeled / visible-text toggles — use ToggleTextButton</item>
     <item>Settings-style on/off fields — use Switch</item>
     <item>One-shot actions with no pressed state — use IconButton</item>
   </when_not_to_use>
+
   <prop name="interpolateIcons" kind="react">
     <description>When `pressedIcon` is set, crossfade and rotate between resting and pressed icons (`data-interpolate=&quot;true&quot;`). When `false`, swap instantly with no transition.</description>
   </prop>

package/dist/specs/components/toggle-button/usage.xml

@@ -7,6 +7,7 @@
   <do>Temporal pressed feedback (e.g. copy) with optional `interpolateIcons` crossfade</do>
   <do>Segmented toolbars: nest ToggleButtons with `value` inside ToggleGroup; label each control and the group</do>
   <do>Optional chrome: wrap with Tooltip.Trigger / Badge — keep the accessible name on the ToggleButton</do>
+  <dont>Labeled / visible-text toggles — use ToggleTextButton (do not stuff text into the icon-only API)</dont>
   <dont>Using IconButton for persistent or temporal pressed toolbar state</dont>
   <dont>Using Switch for compact icon-only toolbar toggles</dont>
   <dont>Passing `icon` or `render` — ToggleButton owns icon swap and Toggle render wiring; use `restingIcon` / `pressedIcon`</dont>
@@ -14,3 +15,4 @@
   <dont>Omitting `value` on ToggleButton children inside a ToggleGroup</dont>
   <dont>Omitting both `aria-label` and `aria-labelledby`</dont>
 </usage>
+

package/dist/specs/components/toggle-group/patterns.xml

@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <patterns surface="toggle-group">
-  <!-- Sources: viraui-app — cleaned (no handlers, no i18n, no theme store). Compound: ToggleGroup + ToggleButton children with value. -->
+  <!-- Sources: viraui-app — cleaned (no handlers, no i18n, no theme store). Compound: ToggleGroup + ToggleButton and/or ToggleTextButton children with value. -->
+
 
   <example title="Mode switcher chrome">
     <tsx><![CDATA[

package/dist/specs/components/toggle-group/usage.xml

@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <usage surface="toggle-group">
-  <do>Segmented icon toolbars such as text alignment, formatting, or mode switchers</do>
-  <do>Single- or multi-select pressed states across related ToggleButton items (`value` / `defaultValue` as `string[]`)</do>
-  <do>Compose only ToggleButton children — each child needs a `value` plus `aria-label` / `aria-labelledby`</do>
+  <do>Segmented toolbars such as text alignment, formatting, or mode switchers</do>
+  <do>Single- or multi-select pressed states across related ToggleButton and/or ToggleTextButton items (`value` / `defaultValue` as `string[]`)</do>
+  <do>Compose ToggleButton and/or ToggleTextButton children — each child needs a `value`; icon-only children also need `aria-label` / `aria-labelledby`</do>
   <do>Label the group root with `aria-label` or `aria-labelledby`</do>
   <do>Optional Surface chrome around the group for bordered toolbar shells — Stack gap is owned by ToggleGroup</do>
-  <dont>Omitting `value` on ToggleButton children inside a group</dont>
+  <dont>Omitting `value` on ToggleButton / ToggleTextButton children inside a group</dont>
   <dont>Using Switch for icon-only toolbar toggle sets</dont>
   <dont>Using ToggleGroup for tabbed panel navigation — use Tabs</dont>
-  <dont>Using ToggleGroup for a lone one-off toggle — use ToggleButton alone</dont>
+  <dont>Using ToggleGroup for a lone one-off toggle — use ToggleButton or ToggleTextButton alone</dont>
   <dont>Embedding Surface chrome inside the component — wrap demos or app chrome at the consumer</dont>
 </usage>

package/dist/specs/components/toggle-text-button/a11y.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<a11y surface="toggle-text-button">
+  <rule>Prefer accessible name from visible text children</rule>
+  <rule>Empty or whitespace-only children require aria-label or aria-labelledby</rule>
+  <rule>Base UI Toggle exposes aria-pressed on the rendered button</rule>
+  <rule>Addon is decorative (aria-hidden) unless it is the sole content path — prefer text label; icon-only → ToggleButton</rule>
+  <rule>Keep the accessible name stable when loading state changes</rule>
+</a11y>

package/dist/specs/components/toggle-text-button/meta.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<meta id="toggle-text-button" title="ToggleTextButton" category="action" shared_contract="button">
+  <summary>Labeled two-state toggle on Base UI Toggle with Button chrome; visible text children, optional addon / pressedVariant; no resting/pressed icon pair.</summary>
+  <exports>
+    <export name="ToggleTextButton" />
+  </exports>
+  <related>
+    <ref id="button" />
+    <ref id="toggle-button" />
+    <ref id="toggle-group" />
+  </related>
+  <units>
+    <unit kind="a11y" href="a11y.xml" />
+    <unit kind="props" href="props.xml" />
+    <unit kind="usage" href="usage.xml" />
+    <unit kind="patterns" href="patterns.xml" />
+  </units>
+  <base_ui href="https://base-ui.com/react/components/toggle#api-reference" />
+</meta>

package/dist/specs/components/toggle-text-button/patterns.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<patterns surface="toggle-text-button">
+  <example title="Labeled press">
+    <tsx><![CDATA[
+<ToggleTextButton variant="flat" pressedVariant="primary">
+  Bold
+</ToggleTextButton>
+]]></tsx>
+    <notes>Visible text supplies the accessible name. Default resting `variant` is `flat`; set `pressedVariant` for pressed chrome.</notes>
+  </example>
+
+  <example title="Addon + label">
+    <tsx><![CDATA[
+<ToggleTextButton
+  addon={<Bell aria-hidden />}
+  addonPosition="start"
+  pressedVariant="secondary"
+>
+  Notify
+</ToggleTextButton>
+]]></tsx>
+    <notes>Button addon is decorative; keep the text label for naming. Omit glyph size props — Button CSS sizes via `--vui-button-icon-size`.</notes>
+  </example>
+
+  <example title="Mixed ToggleGroup">
+    <tsx><![CDATA[
+<ToggleGroup aria-label="Editor options" defaultValue={['bold']}>
+  <ToggleTextButton value="bold" pressedVariant="secondary">
+    Bold
+  </ToggleTextButton>
+  <ToggleTextButton value="notify" addon={<Bell aria-hidden />} pressedVariant="secondary">
+    Notify
+  </ToggleTextButton>
+  <ToggleButton
+    value="lock"
+    aria-label="Lock"
+    restingIcon={<Lock aria-hidden />}
+    pressedVariant="secondary"
+  />
+</ToggleGroup>
+]]></tsx>
+    <notes>ToggleGroup children may be ToggleTextButton and/or ToggleButton; each needs `value`. Icon-only siblings still need `aria-label`.</notes>
+  </example>
+</patterns>

package/dist/specs/components/toggle-text-button/props.xml

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<props surface="toggle-text-button">
+  <when_to_use>
+    <item>Labeled toolbar or settings toggles with visible text</item>
+    <item>Two-state actions that share Button size, variant, addon, loading, and pill chrome</item>
+    <item>ToggleGroup segments that need a text label instead of an icon-only control</item>
+  </when_to_use>
+  <when_not_to_use>
+    <item>Icon-only two-state controls — use ToggleButton</item>
+    <item>Settings-style on/off fields without button chrome — use Switch</item>
+    <item>One-shot actions with no pressed state — use Button</item>
+  </when_not_to_use>
+  <prop name="addon" kind="react">
+    <description>Decorative addon rendered alongside the button label. Pass any React element; use a named icon from `@viraui/icons/react` or `&lt;Chip /&gt;` for status chips. Omit glyph `size` / width / height — Button CSS sizes SVG via `--vui-button-icon-size`.</description>
+  </prop>
+  <prop name="addonPosition" kind="react">
+    <description>Controls whether the addon appears before or after the label.</description>
+  </prop>
+  <prop name="loading" kind="react">
+    <description>Shows a centered spinner overlay while preserving the original content width.</description>
+  </prop>
+  <prop name="pill" kind="react">
+    <description>Applies a fully rounded pill shape to the button.</description>
+  </prop>
+  <prop name="pressedVariant" kind="react">
+    <description>Visual variant while the toggle is pressed.</description>
+  </prop>
+  <prop name="size" kind="react">
+    <description>Controls the visual button size.</description>
+  </prop>
+  <prop name="variant" kind="react">
+    <description>Visual variant while the toggle is not pressed.</description>
+  </prop>
+  <prop name="background" kind="css">
+    <description>Button fill; variant and state selectors preset this.</description>
+  </prop>
+  <prop name="color" kind="css">
+    <description>Button label and icon color.</description>
+  </prop>
+  <prop name="height" kind="css">
+    <description>Button block size; size prop presets via data attributes.</description>
+  </prop>
+  <prop name="icon-size" kind="css">
+    <description>Addon icon size inside the button (`--vui-button-icon-size`). Prefer this over setting `size` on the glyph ReactNode.</description>
+  </prop>
+  <prop name="padding-block" kind="css">
+    <description>Vertical padding inside the button.</description>
+  </prop>
+  <prop name="padding-inline" kind="css">
+    <description>Horizontal padding inside the button.</description>
+  </prop>
+  <prop name="radius" kind="css">
+    <description>Corner radius; pill sets full radius via data-pill.</description>
+  </prop>
+  <prop name="spinner-color" kind="css">
+    <description>Loading spinner color on the root.</description>
+  </prop>
+</props>

package/dist/specs/components/toggle-text-button/usage.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<usage surface="toggle-text-button">
+  <do>Labeled toolbar, filter, or settings toggles with visible text children</do>
+  <do>Optional Button `addon` / `addonPosition` / `size` / `loading` / `pill` chrome beside the label</do>
+  <do>Resting `variant` default `flat`; optional `pressedVariant` when pressed</do>
+  <do>Segmented toolbars: nest ToggleTextButton (and/or ToggleButton) with `value` inside ToggleGroup; label the group</do>
+  <do>Omit glyph `size` / width / height on `addon` — host CSS sizes SVG via `--vui-button-icon-size`</do>
+  <dont>Icon-only two-state controls — use ToggleButton with `restingIcon` / `pressedIcon`</dont>
+  <dont>Passing `restingIcon`, `pressedIcon`, `interpolateIcons`, or `render` — not part of this API</dont>
+  <dont>Omitting `value` on ToggleTextButton children inside a ToggleGroup</dont>
+  <dont>Empty/whitespace children without `aria-label` or `aria-labelledby`</dont>
+  <dont>Using Switch when Button chrome and pressed variant are the desired pattern</dont>
+</usage>

package/dist/specs/index.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<index package="@viraui/react" version="2026.9.1" generated="2026-10-15T08:18:55.911Z">
+<index package="@viraui/react" version="2026.10.0" generated="2026-10-16T10:31:41.253Z">
   <categories>
     <category id="layout" />
     <category id="action" />
@@ -511,6 +511,16 @@
       <unit kind="patterns" href="components/toggle-group/patterns.xml" />
     </units>
   </entry>
+  <entry id="toggle-text-button" category="action" title="ToggleTextButton">
+    <summary>Labeled two-state toggle on Base UI Toggle with Button chrome; visible text children, optional addon / pressedVariant; no resting/pressed icon pair.</summary>
+    <units>
+      <unit kind="meta" href="components/toggle-text-button/meta.xml" />
+      <unit kind="a11y" href="components/toggle-text-button/a11y.xml" />
+      <unit kind="props" href="components/toggle-text-button/props.xml" />
+      <unit kind="usage" href="components/toggle-text-button/usage.xml" />
+      <unit kind="patterns" href="components/toggle-text-button/patterns.xml" />
+    </units>
+  </entry>
   <entry id="typewriter" category="typography" title="Typewriter">
     <summary>Decorative inline typewriter animation that inherits typography and color from a parent text primitive.</summary>
     <units>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viraui/react",
-  "version": "2026.9.1",
+  "version": "2026.10.0",
   "private": false,
   "files": [
     "dist"
@@ -28,7 +28,7 @@
   },
   "devDependencies": {
     "@base-ui/react": ">=1.8.0",
-    "@viraui/foundation": "2026.9.1",
+    "@viraui/foundation": "2026.10.0",
     "@viraui/icons": "2026.1.0",
     "@viraui/postcss-config": "2026.0.0",
     "@viraui/tsconfig": "2026.0.0",