Button

A theme‑aware Button with variants, sizes, disabled and loading states. Now supports global default props & per‑variant overrides via a context provider.

---

Quick start

import { Button } from "@kousta-ui/components";

export default function Example() {
  return (
    <div style={{ display: "flex", gap: 12 }}>
      <Button>Primary</Button>
      <Button variant="success">Success</Button>
      <Button variant="danger">Delete</Button>
    </div>
  );
}

Preview

---

Props

Name	Type	Description	Required	Default
loading	boolean	Shows a loading indicator and disables interaction.	No	false
loadingIndicator	string | ReactNode	Custom content to render while loading.	No	"Loading..."
disabled	boolean	Disables the button.	No	false
variant	ButtonVariant | string	Visual style (supports built‑in and custom provider variants).	No	"primary"
size	"sm" | "md" | "lg"	Size scale.	No	"md"
type	"submit" | "reset" | "button"	Native button type.	No	"button"
onClick	(e: React.MouseEvent<HTMLButtonElement>) => void	Click handler.	No	—
...rest	ComponentPropsWithoutRef<"button">	Any native <button> props (e.g., aria-*, style).	—	—

---

Variants

All color variants are available in solid, outline, light, and link styles for each color:

• primary, primary-outline, primary-light, primary-link
• success, success-outline, success-light, success-link
• danger, danger-outline, danger-light, danger-link
• neutral, neutral-outline, neutral-light, neutral-link
• warning, warning-outline, warning-light, warning-link

<div style={{ display: "flex", gap: 12, flexWrap: "wrap" }}>
  <Button variant="primary">Primary</Button>
  <Button variant="primary-outline">Primary</Button>
  <Button variant="primary-light">Primary</Button>
  <Button variant="primary-link">Primary</Button>

  <Button variant="neutral">Neutral</Button>
  <Button variant="neutral-outline">Neutral</Button>
  <Button variant="neutral-light">Neutral</Button>
  <Button variant="neutral-link">Neutral</Button>
</div>

Preview

Variantprimaryprimary-outlineprimary-lightprimary-linksuccesssuccess-outlinesuccess-lightsuccess-linkdangerdanger-outlinedanger-lightdanger-linkneutralneutral-outlineneutral-lightneutral-linkwarningwarning-outlinewarning-lightwarning-link

Define your own variants

With the ComponentPropsProvider you can provide your own pre‑defined button variant, as well as override the existing ones.

Example

import { Button, ComponentPropsProvider } from "@kousta-ui/components";

<ComponentPropsProvider
  button={{
    /* override default variant for all Buttons (unless locally set) */
    variant: "neutral",
    /* new custom variants */
    variants: {
      ghost: {
        className: "btn-ghost",
      },
      info: {
        className: "bg-blue-500 text-white rounded-md",
      },
    },
  }}
>
  <Button variant="ghost">Ghost</Button>
  <Button variant="info">Info</Button>
</ComponentPropsProvider>

---

Size

Button accepts three sizes: sm, md, lg. Default is md.

<Button size="sm">Small Button</Button>
<Button size="md">Medium Button</Button> {/* default */}
<Button size="lg">Large Button</Button>

Preview

Override size app‑wide

Use the provider to set a default size for a subtree. Component props always override provider defaults.

import { Button, ComponentPropsProvider } from "@kousta-ui/components";

<>
  <Button>Medium (default)</Button>
  <ComponentPropsProvider button={{ size: "lg" }}>
    {/* uses provider default: lg */}
    <Button>Large (provider default)</Button>
    {/* local prop wins over provider */}
    <Button size="sm">Small (local override)</Button>
  </ComponentPropsProvider>
</>

Preview

---

Loading & disabled

• When loading is true, the component sets data-loading="true" and is disabled to prevent duplicate actions.
• When disabled is true, the button is non‑interactive.
• Use loadingIndicator to customize the loading content (text or React node).

<div style={{ display: "flex", gap: 12, alignItems: "center" }}>
  <Button loading>Saving…</Button>
  <Button
    loading
    loadingIndicator={<span style={{ display: "inline-flex", gap: 6 }}><i className="spinner" />Please wait</span>}
    variant="neutral-outline"
  />
  <Button disabled variant="neutral-outline">Disabled</Button>
</div>

Preview

Override loadingIndicator

// Local override
<Button loading loadingIndicator="Submitting…">Submit</Button>

// Provider default for a subtree
<ComponentPropsProvider button={{ loadingIndicator: "Please wait…" }}>
  <Button loading>Submit</Button> {/* renders "Please wait…" */}
</ComponentPropsProvider>

---

Global defaults & per‑variant overrides (via Provider) New

Use ComponentPropsProvider to define app‑wide defaults for Button and to create custom variants that map to native button props (style/className/aria/etc.).

import { ComponentPropsProvider, Button } from "@kousta-ui/components";

export default function App() {
  return (
    <ComponentPropsProvider
      button={{
        /** default props if not provided by <Button /> */
        size: "sm",
        type: "submit",
        variant: "primary",
        className: "my-shared-btn-class",
        style: { borderRadius: 12 },

        /** define custom variants (keys you can pass to `variant`) */
        variants: {
          mine: {
            // Anything valid for <button>
            style: { backgroundColor: "red", color: "green" },
          },
          ghost: {
            className: "btn-ghost",
            "aria-live": "polite",
          },
        },
        /** default loading text if <Button loading loadingIndicator /> not provided */
        loadingIndicator: "Loading…",
      }}
    >
      {/* uses provider defaults: size=sm, type=submit */}
      <Button>Submit</Button>

      {/* uses custom provider variant mapping */}
      <Button variant="mine">Custom</Button>
    </ComponentPropsProvider>
  );
}

Preview

How precedence works

• Component props win over provider defaults. If you pass size="lg" on a button, it overrides the provider’s size.
• Provider variants[variant] are merged with the component props. For style, provider style is merged first, then the component style is applied so your local styles win.
• Class names are concatenated in this order: provider.className → CSS classes for variant and size → component className.

---

Accessibility

• Semantic <button type="button|submit|reset">.
• Disabled and loading states set disabled to block interaction.
• Add aria-busy={loading} if you customize the loading UI.
• Ensure contrast between text and background meets WCAG AA.

Tip If the label is just an icon, add an accessible name with aria-label.

---

Patterns

Submit buttons in forms

<form onSubmit={handleSubmit}>
  <Button type="submit" loading={isSaving} loadingIndicator="Saving…">
    Save changes
  </Button>
</form>

Destructive action

<Button variant="danger" onClick={onDelete}>Delete</Button>

Secondary emphasis

<Button variant="neutral-outline">Cancel</Button>

App‑wide sizing & type defaults

<ComponentPropsProvider button={{ size: "sm", type: "submit" }}>
  {/* becomes a small submit button unless overridden */}
  <Button>Save</Button>
</ComponentPropsProvider>

Custom “ghost” variant via provider

<ComponentPropsProvider button={{ variants: { ghost: { className: "btn-ghost" } } }}>
  <Button variant="ghost">Ghost</Button>
</ComponentPropsProvider>

---

Types (reference)

import { ComponentPropsWithoutRef, ReactNode } from "react";

type ButtonColor = "primary" | "warning" | "neutral" | "danger" | "success";
type ButtonColoringStyle = "outline" | "light" | "link" | "";

export type ButtonVariant =
  | ButtonColor
  | `${ButtonColor}-${Exclude<ButtonColoringStyle, "">}`;

export type ButtonProps = {
  loading?: boolean;
  loadingIndicator?: string | ReactNode;
  disabled?: boolean;
  variant?: ButtonVariant | string;
  size?: "sm" | "md" | "lg";
  type?: "submit" | "reset" | "button";
  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
} & ComponentPropsWithoutRef<"button">;

---

Styles & customization

Runtime classes

• Base
  • kui-button
• Variant
  • kui-button-{variant} (example: kui-button-primary-light)
• Size
  • kui-button-{size} (example: kui-button-lg)
• Loading UI
  • kui-button-loading (rendered inside the button when loading is true)

Tokens used by the default styles

• Spacing
  • --kui-spacing-xs, --kui-spacing-sm, --kui-spacing-md, --kui-spacing-lg
• Rounding
  • --kui-rounded
• Colors
  • --kui-primary-*, --kui-success-*, --kui-danger-*, --kui-neutral-*, --kui-warning-*