Button

<r-button>APIStyle tokensPlaygroundSource

Button component for triggering instant actions with multiple styles and states.

Use when you need a clickable action control with ready-made primary/contrast/warning/text styles plus disabled and icon support: reach for <r-button> instead of styling a raw <button>.

Quick Start

Basic Usage

<r-button>Button</r-button>

API Reference

Properties

Button Types type

<r-button type="primary">Primary Button</r-button>
<r-button type="warning">Warning Button</r-button>
<r-button type="text">Text Button</r-button>
<r-button>Default Button</r-button>

primary is the monochrome action (from the Geist design language): black-on-white in light mode, white-on-black in dark mode. Blue carries no brand meaning here; it is reserved for links and the focus ring. It rides the --ran-color-primary* tokens (--ran-color-primary, -hover, -active, and --ran-color-primary-text for the inverse ink); see Theme & Tokens.

Under data-ran-surface="glass", the default button frosts (Apple glass); primary and warning stay solid (Apple glassProminent) so emphasis does not wash out. Switch the site to Liquid glass to see the difference on the default control above.

Disabled State disabled

Disabled buttons reject pointer, keyboard and programmatic click() activation. Re-enabling restores the same control and its accessible name.

focus(options?: FocusOptions) focuses the enabled keyboard surface and forwards native focus options. Overlays can call it to restore their trigger after dismissal; a disabled button does not receive focus.

<r-button type="primary" disabled>Primary Button</r-button>
<r-button type="warning" disabled>Warning Button</r-button>
<r-button type="text" disabled>Text Button</r-button>
<r-button disabled>Default Button</r-button>

Icon Button icon

<r-button type="default" icon="user">Default Button</r-button>
<r-button type="primary" icon="home">Primary Button</r-button>

Effect Control effect

The click ripple is on by default. Set effect="false" for a plain button without it. The two buttons below differ only in that attribute, so you can compare them by clicking each. The ripple is a pointer-device effect and only renders from a viewport width of 1024px.

<r-button type="primary" icon="home">Ripple (default)</r-button>
<r-button type="primary" icon="home" effect="false">No ripple</r-button>

Only the literal value false turns the ripple off; effect="true" and any other value leave it on. From script, set the property as a boolean: button.effect = false.

Events

<r-button onclick="handleClick()">Click Me</r-button>

<script>
  function handleClick() {
    console.log('Button clicked');
  }
</script>

Styling

<r-button> exposes 43 CSS custom properties of its own: --ran-btn-background, --ran-btn-color, --ran-btn-border-color, their hover / active variants, and the warning variant's three, plus the semantic tokens it reads from the theme.

/* one button, or every button under a scope */
r-button {
  --ran-btn-background: var(--ran-color-bg-subtle);
  --ran-btn-hover-background: var(--ran-color-bg-hover);
  --ran-btn-border-radius: var(--ran-radius-full);
}

Reach for a semantic token instead when the change is not button-specific: overriding --ran-color-primary restyles the primary action everywhere, not just here.

Parts: button · content

r-button::part(content) {
  letter-spacing: 0.02em;
}

The full list is in style tokens; which token to reach for is the design system.

Playground