moduix

Button

A composable action control with variants, sizes, icons, and loading states.

API Reference

Original primitive API

Behavior, accessibility details, and low-level props are documented by Base UI.

Base UI API

Basic

import { Button } from "moduix";export function ButtonDemo() {  return <Button>Save Changes</Button>;}

Full list of component variables available for project-level overrides.

PropertyDefaultDescription
--button-border-widthvar(--border-width-sm)Controls base button border width.
--button-colorvar(--color-foreground)Controls base button text and icon color.
--button-content-gapvar(--spacing-2)Controls spacing between text and icons.
--button-default-bgvar(--color-primary)Controls default variant background.
--button-default-bg-hovervar(--color-foreground)Controls default variant hover background.
--button-default-border-colorvar(--color-primary)Controls default variant border color.
--button-default-colorvar(--color-primary-foreground)Controls default variant text and icon color.
--button-destructive-bgvar(--color-destructive)Controls destructive variant background.
--button-destructive-border-colorvar(--color-destructive)Controls destructive variant border color.
--button-destructive-colorvar(--color-primary-foreground)Controls destructive variant text and icon color.
--button-destructive-hover-brightness0.96Controls destructive variant hover brightness filter.
--button-destructive-outline-bgvar(--color-background)Controls destructive-outline variant background.
--button-destructive-outline-bg-hovervar(--color-destructive)Controls destructive-outline variant hover background.
--button-destructive-outline-border-colorvar(--color-destructive)Controls destructive-outline variant border color.
--button-destructive-outline-colorvar(--color-destructive)Controls destructive-outline variant text and icon color.
--button-destructive-outline-color-hovervar(--button-destructive-color)Controls destructive-outline variant hover text and icon color.
--button-disabled-opacityvar(--opacity-disabled)Controls disabled state opacity.
--button-focus-ring-colorvar(--color-ring)Controls focus-visible outline color.
--button-focus-ring-offsetvar(--button-border-width)Controls focus-visible outline offset.
--button-focus-ring-widthvar(--border-width-md)Controls focus-visible outline width.
--button-font-sizevar(--text-sm)Controls base button font size.
--button-font-size-xsvar(--text-xs)Controls `xs` button font size.
--button-font-size-lgvar(--text-md)Controls `lg` button font size.
--button-font-size-xlvar(--text-lg)Controls `xl` button font size.
--button-font-weightvar(--weight-medium)Controls button font weight.
--button-ghost-bgtransparentControls ghost variant background.
--button-ghost-bg-hovervar(--color-accent)Controls ghost variant hover background.
--button-ghost-border-colortransparentControls ghost variant border color.
--button-ghost-colorvar(--color-foreground)Controls ghost variant text and icon color.
--button-icon-size1remControls nested SVG icon size.
--button-line-heightvar(--line-height-text-sm)Controls base button line height.
--button-line-height-xsvar(--line-height-text-xs)Controls `xs` button line height.
--button-line-height-lgvar(--line-height-text-md)Controls `lg` button line height.
--button-line-height-xlvar(--line-height-text-lg)Controls `xl` button line height.
--button-link-colorvar(--color-primary)Controls link variant color.
--button-link-color-hovervar(--color-foreground)Controls link variant hover color.
--button-link-text-decorationunderlineControls link variant text decoration.
--button-link-underline-offset0.25emControls link variant underline offset.
--button-outline-bgvar(--color-background)Controls outline variant background.
--button-outline-bg-hovervar(--color-accent)Controls outline variant hover background.
--button-outline-border-colorvar(--color-border)Controls outline variant border color.
--button-outline-colorvar(--color-foreground)Controls outline variant text and icon color.
--button-padding-x-xs0.625remControls `xs` button horizontal padding.
--button-padding-x-sm0.75remControls `sm` button horizontal padding.
--button-padding-x-md1remControls `md` button horizontal padding.
--button-padding-x-lg1.25remControls `lg` button horizontal padding.
--button-padding-x-xl1.5remControls `xl` button horizontal padding.
--button-padding-y-xs0.25remControls `xs` button vertical padding.
--button-padding-y-sm0.375remControls `sm` button vertical padding.
--button-padding-y-md0.5remControls `md` button vertical padding.
--button-padding-y-lg0.625remControls `lg` button vertical padding.
--button-padding-y-xl0.75remControls `xl` button vertical padding.
--button-radiusvar(--radius-md)Controls button corner radius.
--button-secondary-bgvar(--color-secondary)Controls secondary variant background.
--button-secondary-bg-hovervar(--color-accent)Controls secondary variant hover background.
--button-secondary-border-colorvar(--color-secondary)Controls secondary variant border color.
--button-secondary-colorvar(--color-secondary-foreground)Controls secondary variant text and icon color.
--button-size-icon-smvar(--size-sm)Controls `icon-sm` button size.
--button-size-icon-mdvar(--size-lg)Controls `icon-md` button size.
--button-size-icon-lgvar(--size-xl)Controls `icon-lg` button size.
--button-size-xsvar(--size-xs)Controls `xs` button min height.
--button-size-smvar(--size-sm)Controls `sm` button min height.
--button-size-mdvar(--size-lg)Controls `md` button min height.
--button-size-lgvar(--size-xl)Controls `lg` button min height.
--button-size-xl3.5remControls `xl` button min height.
--button-spinner-animationvar(--animation-spin)Controls built-in spinner animation.
--button-spinner-border-widthvar(--border-width-sm)Controls built-in spinner border width.
--button-spinner-radiusvar(--radius-full)Controls built-in spinner corner radius.
--button-spinner-size0.875remControls built-in spinner size.
--button-transitionvar(--transition-default)Controls transition timing for interactive states.

Interactive variables scoped for docs preview without changing size scale tokens.

PropertyValueDefaultDescription
--button-border-widthvar(--border-width-sm)Controls base button border width.
--button-colorvar(--color-foreground)Controls base button text and icon color.
--button-content-gapvar(--spacing-2)Controls spacing between text and icons.
--button-default-bgvar(--color-primary)Controls default variant background.
--button-default-bg-hovervar(--color-foreground)Controls default variant hover background.
--button-default-border-colorvar(--color-primary)Controls default variant border color.
--button-default-colorvar(--color-primary-foreground)Controls default variant text and icon color.
--button-destructive-bgvar(--color-destructive)Controls destructive variant background.
--button-destructive-border-colorvar(--color-destructive)Controls destructive variant border color.
--button-destructive-colorvar(--color-primary-foreground)Controls destructive variant text and icon color.
--button-destructive-hover-brightness0.96Controls destructive variant hover brightness filter.
--button-destructive-outline-bgvar(--color-background)Controls destructive-outline variant background.
--button-destructive-outline-bg-hovervar(--color-destructive)Controls destructive-outline variant hover background.
--button-destructive-outline-border-colorvar(--color-destructive)Controls destructive-outline variant border color.
--button-destructive-outline-colorvar(--color-destructive)Controls destructive-outline variant text and icon color.
--button-destructive-outline-color-hovervar(--button-destructive-color)Controls destructive-outline variant hover text and icon color.
--button-disabled-opacityvar(--opacity-disabled)Controls disabled state opacity.
--button-focus-ring-colorvar(--color-ring)Controls focus-visible outline color.
--button-focus-ring-offsetvar(--button-border-width)Controls focus-visible outline offset.
--button-focus-ring-widthvar(--border-width-md)Controls focus-visible outline width.
--button-font-sizevar(--text-sm)Controls base button font size.
--button-font-size-xsvar(--text-xs)Controls `xs` button font size.
--button-font-size-lgvar(--text-md)Controls `lg` button font size.
--button-font-size-xlvar(--text-lg)Controls `xl` button font size.
--button-font-weightvar(--weight-medium)Controls button font weight.
--button-ghost-bgtransparentControls ghost variant background.
--button-ghost-bg-hovervar(--color-accent)Controls ghost variant hover background.
--button-ghost-border-colortransparentControls ghost variant border color.
--button-ghost-colorvar(--color-foreground)Controls ghost variant text and icon color.
--button-icon-size1remControls nested SVG icon size.
--button-line-heightvar(--line-height-text-sm)Controls base button line height.
--button-line-height-xsvar(--line-height-text-xs)Controls `xs` button line height.
--button-line-height-lgvar(--line-height-text-md)Controls `lg` button line height.
--button-line-height-xlvar(--line-height-text-lg)Controls `xl` button line height.
--button-link-colorvar(--color-primary)Controls link variant color.
--button-link-color-hovervar(--color-foreground)Controls link variant hover color.
--button-link-text-decorationunderlineControls link variant text decoration.
--button-link-underline-offset0.25emControls link variant underline offset.
--button-outline-bgvar(--color-background)Controls outline variant background.
--button-outline-bg-hovervar(--color-accent)Controls outline variant hover background.
--button-outline-border-colorvar(--color-border)Controls outline variant border color.
--button-outline-colorvar(--color-foreground)Controls outline variant text and icon color.
--button-padding-x-xs0.625remControls `xs` button horizontal padding.
--button-padding-x-sm0.75remControls `sm` button horizontal padding.
--button-padding-x-md1remControls `md` button horizontal padding.
--button-padding-x-lg1.25remControls `lg` button horizontal padding.
--button-padding-x-xl1.5remControls `xl` button horizontal padding.
--button-padding-y-xs0.25remControls `xs` button vertical padding.
--button-padding-y-sm0.375remControls `sm` button vertical padding.
--button-padding-y-md0.5remControls `md` button vertical padding.
--button-padding-y-lg0.625remControls `lg` button vertical padding.
--button-padding-y-xl0.75remControls `xl` button vertical padding.
--button-radiusvar(--radius-md)Controls button corner radius.
--button-secondary-bgvar(--color-secondary)Controls secondary variant background.
--button-secondary-bg-hovervar(--color-accent)Controls secondary variant hover background.
--button-secondary-border-colorvar(--color-secondary)Controls secondary variant border color.
--button-secondary-colorvar(--color-secondary-foreground)Controls secondary variant text and icon color.
--button-size-icon-smvar(--size-sm)Controls `icon-sm` button size.
--button-size-icon-mdvar(--size-lg)Controls `icon-md` button size.
--button-size-icon-lgvar(--size-xl)Controls `icon-lg` button size.
--button-size-xsvar(--size-xs)Controls `xs` button min height.
--button-size-smvar(--size-sm)Controls `sm` button min height.
--button-size-mdvar(--size-lg)Controls `md` button min height.
--button-size-lgvar(--size-xl)Controls `lg` button min height.
--button-size-xl3.5remControls `xl` button min height.
--button-spinner-animationvar(--animation-spin)Controls built-in spinner animation.
--button-spinner-border-widthvar(--border-width-sm)Controls built-in spinner border width.
--button-spinner-radiusvar(--radius-full)Controls built-in spinner corner radius.
--button-spinner-size0.875remControls built-in spinner size.
--button-transitionvar(--transition-default)Controls transition timing for interactive states.

Anatomy

Button is composed as one interactive root with optional internal loading slots. In common usage, compose content as children and optionally enable loading states.

Button
├─ content
└─ loadingIndicator (when loading)
   └─ spinner (default)
PartRole
ButtonInteractive root. Handles click, disabled, loading, and focus states.
content slotWrapper around button children so content layout stays stable.
loadingIndicatorSlot rendered in loading state; accepts custom indicator via props.
spinnerDefault spinner inside loadingIndicator when no custom indicator is provided.

The root exposes data-disabled from Base UI and data-loading from moduix. Use these attributes or CSS variables when styling state from CSS.

Composition

Use Button behavior props such as render, nativeButton, disabled, and focusableWhenDisabled. Use className for the root button. Use classNames for internal slots that are rendered by the component:

<Button
  className={styles.button}
  classNames={{
    content: styles.content,
    loadingIndicator: styles.loadingIndicator,
    spinner: styles.spinner,
  }}
/>

For submit buttons, pass type="submit". For links, style an <a> directly instead of rendering an anchor through Button; Base UI Button intentionally keeps button semantics.

Examples

Variants

Use variant to match the intent of the action. For navigation links, style an <a> directly instead of rendering a link through Button.

import { Button } from "moduix";export function ButtonVariantsDemo() {  return (    <div>      <Button>Default</Button>      <Button variant="outline">Outline</Button>      <Button variant="secondary">Secondary</Button>      <Button variant="destructive">Destructive</Button>      <Button variant="destructive-outline">Destructive Outline</Button>      <Button variant="ghost">Ghost</Button>      <Button variant="link">Link</Button>    </div>  );}

Sizes

Use text sizes for standard actions and icon sizes for buttons that only contain an icon.

import { Button, StarIcon } from "moduix";export function ButtonSizesDemo() {  return (    <div>      <Button size="xs">Extra-small</Button>      <Button size="sm">Small</Button>      <Button size="md">Medium</Button>      <Button size="lg">Large</Button>      <Button size="xl">Extra-large</Button>      <Button size="icon-sm" variant="outline" aria-label="Small favorite">        <StarIcon />      </Button>      <Button size="icon-md" variant="outline" aria-label="Favorite">        <StarIcon />      </Button>      <Button size="icon-lg" variant="outline" aria-label="Large favorite">        <StarIcon />      </Button>    </div>  );}

Icons

Pass icons as children. The component does not lock you into a specific icon set.

import { Button, PlusIcon, StarIcon, ArrowUpRightIcon } from "moduix";export function ButtonIconsDemo() {  return (    <div>      <Button>        <PlusIcon />        Create Item      </Button>      <Button size="icon-md" variant="outline" aria-label="Favorites">        <StarIcon />      </Button>      <Button variant="link">        Open Docs        <ArrowUpRightIcon />      </Button>    </div>  );}

Disabled

Use focusableWhenDisabled when the button becomes disabled after focus, for example during a pending action.

import { Button } from "moduix";export function ButtonDisabledDemo() {  return (    <div>      <Button disabled>Disabled</Button>      <Button disabled focusableWhenDisabled variant="outline">        Focusable Disabled      </Button>    </div>  );}

Loading

Use the built-in loading props when an action should keep its size while it is pending.

import { Button } from "moduix";import { useState } from "react";export function LoadingButton() {  const [loading, setLoading] = useState(false);  return (    <Button      loading={loading}      loadingText="Saving"      onClick={() => {        setLoading(true);        setTimeout(() => setLoading(false), 1800);      }}    >      Save Changes    </Button>  );}

Custom Loading Indicator

Pass loadingIndicator to use an icon or spinner from your application.

import { Button, StarIcon } from "moduix";export function CustomLoadingIndicatorDemo() {  return (    <Button      loading      loadingText="Syncing"      variant="outline"      loadingIndicator={<StarIcon className={styles.customLoadingIndicator} />}    >      Sync    </Button>  );}
.customLoadingIndicator {  width: 0.875rem;  height: 0.875rem;  animation: var(--animation-spin);}

Custom Styles

Pass className for the button root and classNames for internal slots when styling with CSS Modules, Tailwind CSS, or CSS-in-JS.

import { Button } from "moduix";export function CustomStylesButtonDemo() {  return (    <Button      className={styles.customButton}      classNames={{        content: styles.customButtonContent,        loadingIndicator: styles.customLoadingIndicatorColor,        spinner: styles.customSpinner,      }}      loading      loadingText="Publishing"    >      Publish    </Button>  );}
.customButton {  border-color: var(--color-primary);  background-color: var(--color-primary);  color: var(--color-primary-foreground);  box-shadow: 0 1px 2px rgb(0 0 0 / 0.08);}.customButtonContent {  letter-spacing: 0.025em;}.customLoadingIndicatorColor {  color: var(--color-primary-foreground);}.customSpinner {  border-width: var(--border-width-md);}

On this page