Skip to content

Button

Get Ritla UI

The main action control, in five styles and four sizes, with a danger variant and a loading state. Its directional icons mirror in Arabic on their own.

Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add button

    Also works with shadcn: npx shadcn@latest add @ritla/button

  2. Dependencies it brings

    @base-ui/react@phosphor-icons/react

  3. Or copy by hand

    Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.

Usage

button.tsx
import { ArrowRightIcon } from "@phosphor-icons/react/ssr";import { Button } from "@/components/ui/button";<Button variant="outline">Cancel</Button><Button iconTrailing={ArrowRightIcon}>Continue</Button><Button danger>Delete project</Button>

Examples

Styles

filled for the main action, one per view. tonal for a strong secondary, outline for alternatives like Cancel, ghost for low-emphasis actions, inverted-ghost on colored surfaces. danger turns any style red.

EnglishMirroredArabic
LTR →

Sizes

lg 56px (default), md 48 for forms, sm 40 for tables and filters, xs 32 for dense UI. The tap target stays at least 48px at every size.

EnglishMirroredArabic
LTR →

States

Hover, pressed and focus come from the pointer and keyboard. loading puts the spinner in the leading slot and keeps focus on the button; disabled switches it off. While pressed it sinks 1px, when motion is allowed. Press Save.

EnglishMirroredArabic
LTR →

Icons

iconLeading and iconTrailing are optional. “Next” uses ArrowRightIcon in both languages and flips in Arabic to point forward; the download icon never mirrors.

EnglishMirroredArabic
LTR →

Spread layout

layout="spread" puts the label at the start and the trailing icon on the end edge, at least 216px wide on lg and md. For calls to action that lead somewhere. The arrow points to the destination (left in Arabic) and nudges toward it on hover and focus; icons that aren't directional stay put.

EnglishMirroredArabic
LTR →

Action order

The main action at the inline end, the alternative before it. In Arabic the whole row mirrors, so the main action stays at the end (the left). Destructive actions get a specific label, never “OK”.

EnglishMirroredArabic
LTR →

API reference

Button

Any other Base UI Button prop passes through (onClick, type…).

PropTypeDefaultDescription
variant"filled" | "tonal" | "outline" | "ghost" | "inverted-ghost""filled"Figma's Style property (style is taken by React).
size"lg" | "md" | "sm" | "xs""lg"Figma's Size: 56, 48, 40 and 32px.
dangerbooleanfalseFigma's Danger: red for destructive actions, with a red focus ring.
childrenReactNodeNoneFigma's Label: the button text.
iconLeadingIconComponentNoneIcon leading: a Phosphor or Ritla UI icon at the inline start.
iconTrailingIconComponentNoneIcon trailing: an icon at the inline end.
layout"default" | "spread""default"Figma's Layout: spread puts the label at the start and the trailing icon on the end edge, and nudges the arrow toward the destination on hover or focus.
loadingbooleanfalseState = Loading: spinner in the leading slot, aria-busy, the button stays focusable and ignores presses.
disabledbooleanfalseState = Disabled.
renderReactElementNoneAnother element with the Button look, usually a link (<a> or <Link>). It keeps its own semantics, so it isn't announced as a button.
classNamestringNoneExtra classes merged with cn(), such as w-full.

Anatomy

A content frame inside a 48 px touch target: an optional leading icon, the label and an optional trailing icon.

  1. 1. Touch targetsize/touch-target

    The outer frame: at least 48 px tall in every size. sm and xs add it without taking layout space.

  2. 2. Contentvariant, danger

    Fill and stroke follow Style; radius/10 at lg, radius/8 at md, radius/6 at sm, radius/4 at xs.

  3. 3. Leading iconiconLeading

    24 at lg, 20 at md, sm and xs. Sits at the inline start.

  4. 4. Labelchildren

    The Label text property: body-16/Semibold, body-14/Semibold at xs.

  5. 5. Trailing iconiconTrailing

    Same sizes as the leading icon. Sits at the inline end and mirrors in RTL.

  6. 6. Loading indicatorloading

    Replaces the leading icon while pending; the label stays so the width does not jump.

  7. 7. Focus ring

    2 px ring on focus-visible only, offset from the content frame.

Usage guidelines

A button starts an action: save, send, create, delete. Which style to use, how to write the label, and the checks before handoff.

1. Choose the style by emphasis

Style shows how important an action is, not what it does. Most screens need one filled button and a few quieter ones. When everything is loud, nothing is.

StyleHow manyUse for
filledOne per viewThe main action of the view: Save, Send, Pay, Create.
tonalOne or twoA strong secondary action that should stay visible next to the main one.
outlineAs neededAlternatives to the main action: Cancel, Back, Skip.
ghostAs neededLow-emphasis actions inside content, cards and toolbars.
inverted-ghostAs neededActions on brand or dark surfaces: banners, hero sections, the inverse toast.
dangerOne, at the end of a flowDestructive actions that lose data. Works on every style; filled only in the confirmation step.

Buttons on a brand surface

A promotion banner with one action.

Do: inverted-ghostWhite text on a translucent fill keeps contrast on brand blue.
Don't: ghost on brandGray text on brand blue fails contrast and looks disabled.

Do

  • Give each view one filled button for its main action.
  • Use inverted-ghost on brand and dark surfaces.
  • Keep the same style for the same action across the product.

Don't

  • Put two filled buttons side by side.
  • Use ghost or outline on a brand surface: their gray text disappears.
  • Pick a style for its color; red means destructive, not important.

2. Write the label

The label says exactly what happens when the button is pressed. Start with a verb and name the object. Write the Arabic label natively: a short verbal noun such as حفظ or إرسال reads as a command in interfaces and stays consistent across the product.

Name the action

The main action on an invoices page.

Do: Verb and objectThe reader knows what happens before pressing.
Don't: Generic label“Click here” describes the gesture, not the result, in both languages.

Do

  • Start with a verb and name the object, as in Create invoice.
  • Keep labels to one to three words.
  • Use sentence case in English; Arabic has no case, so never fake emphasis with size.
  • Use the same verb for the same action everywhere: Delete is never also Remove.

Don't

  • Use “Click here”, “OK” or “Yes” when the action can be named.
  • End a label with punctuation or an ellipsis.
  • Truncate a label; shorten the wording instead.
  • Translate word by word: “Submit” becomes إرسال, not a literal قدّم.

3. Icons

An icon helps people find a button faster; the label still carries the meaning. Use a leading icon to reinforce the action (Plus for Create, Download for Export) and a trailing arrow only for moving forward. Directional icons must use their RTL variant in Arabic buttons.

Arrows follow the reading direction

A “Next” button in an Arabic checkout.

Do: RTL arrowThe arrow points left, toward the next step in Arabic.
Don't: LTR arrow in ArabicThe arrow points back to the previous step.

Do

  • Use one icon at most, leading or trailing.
  • Put a trailing arrow on “Next” and “Continue”; in RTL it points left.
  • Pick the RTL = Yes variant of arrows and chevrons in Arabic buttons.

Don't

  • Use both a leading and a trailing icon.
  • Keep an arrow pointing right in an Arabic button.
  • Use an icon-only Button; use Icon Button with a label instead.

4. Size

lg (56) is the default, as in code, and the size for the main action on mobile and in hero sections. md (48) fits form buttons, sm (40) tables and filters, xs (32) dense toolbars. sm and xs add an invisible 48 px hit area in code, so give them room.

One size per group

Form actions.

Do: Matching sizesBoth buttons share one baseline and one height.
Don't: Mixed sizesThe smaller button looks less important and harder to hit.

Do

  • Use one size for every button in a group.
  • Leave at least space-8 between sm and xs buttons so hit areas don't overlap.
  • Make the main action full width at the bottom of mobile screens.

Don't

  • Mix sizes in one group.
  • Use xs as the only action on a touch screen.
  • Set a fixed height on a button; Arabic labels need taller lines.

5. Order and placement

In a group, the main action sits at the inline end: on the right in English, on the left in Arabic. The alternative comes before it. The order mirrors with the layout, so Arabic screens need RTL buttons in an RTL row, not the English row with Arabic labels.

Main action at the inline end

A dialog footer in Arabic.

Do: RTL orderThe main action, حفظ, sits on the left, where the Arabic reader finishes the row.
Don't: LTR order in ArabicThe main action ends up first, where the reader starts.

Do

  • Put the main action at the inline end of dialogs, forms and footers.
  • Align the group to the inline end of its container.
  • Stack buttons full width on narrow screens, main action on top.

Don't

  • Keep the English order in Arabic screens.
  • Place the main action between two secondary ones.
  • Separate buttons that belong together.

6. Loading and disabled

Loading and Disabled are the two states you set; hover, pressed and focus come from interaction. Change the label to its in-progress form while loading (Save to Saving, حفظ to جارٍ الحفظ). The spinner takes the leading icon slot.

Show progress in the label

Saving a form.

Do: In-progress labelSave changes becomes Saving changes; the spinner takes the leading icon slot.
Don't: Generic loading text“Loading…” no longer says what is being saved.

Do

  • Switch to Loading as soon as the action starts, and back when it ends.
  • Change the label to its in-progress form while loading: Save to Saving, حفظ to جارٍ الحفظ.
  • Explain why a button is disabled next to it, or leave it enabled and show the error on press.

Don't

  • Replace the label with a generic “Loading…”: it no longer says what is happening.
  • Disable a button without saying what's missing.
  • Use Disabled for actions the user can never take; hide them instead.

7. Destructive actions

danger switches any style to the red palette. Use it only when the action deletes or loses something, and confirm anything that can't be undone in a dialog whose filled danger button repeats the exact action.

Do: Name what is lostoutline or ghost with danger on the page; filled with danger only in the confirmation.
Don't: Red on a safe actionLog out and Cancel are not destructive, so they are never red.

Do

  • Name what is lost: Delete project.
  • Use outline or ghost with danger on the page, and filled with danger only in the confirmation.
  • Offer Undo instead of a confirmation when the action can be reversed.

Don't

  • Use red for actions that aren't destructive, like Log out or Cancel.
  • Label a destructive action “OK” or “Yes”.
  • Make the destructive action the default focused button.

Before handoff

  • One filled button per view, at the inline end of its group.
  • Every label starts with a verb and names the object.
  • Arabic screens use RTL variants with RTL arrows.
  • Destructive actions use danger and a specific label.
  • Loading, disabled and error states are designed, not just Enabled.
  • Links that look like buttons are marked as links for development.

Tokens & specs

Every value on Button is a variable or a text style. These are the ones bound on the component, by size and by style.

Sizes

Visible height, inline padding, gap and radius of the Content frame; every size sits in a touch target of size/touch-target (48).

SizeHeight, padding, gap, radiusLabel and icons
lg56 · space-24 · space-8 · radius/10body-16/Semibold · 24
md48 · space-24 · space-8 · radius/8body-16/Semibold · 20
sm40 · space-16 · space-8 · radius/6body-16/Semibold · 20
xs32 · space-12 · space-8 · radius/4body-14/Semibold · 20

Colors

Fill, border and label colour per style in the Enabled state. Light and dark come from the 1. Colors mode, not from separate variants.

StyleFill and borderLabel
filledbackground/brand/solidtext/brand/on-brand
filled · dangerbackground/danger/solidtext/static/white
tonalbackground/brand/fainttext/brand/subtle
tonal · dangerbackground/danger/fainttext/danger/subtle
outlinebackground/surface/lowest · border/gray/softtext/gray/subtle
outline · dangerbackground/surface/lowest · border/danger/softtext/danger/subtle
ghostalpha/tint-12text/gray/subtle
ghost · dangeralpha/tint-12text/danger/subtle
inverted-ghostalpha/tint-12text/static/white

Focus

State=Focused draws the Focus/focus-ring effect style (effects/focus/main) with border-width/thicker; with danger the ring is red. In code it is automatic on :focus-visible.

Accessibility

Keyboard

Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.

KeyAction
TabMoves focus to the button and shows the focus ring (red with danger).
EnterSpaceActivates it. While loading, focus stays and the action doesn't repeat.

ARIA

  • A native <button> (or <a> with render), so no role is needed.
  • Loading sets aria-busy="true" and aria-disabled="true" instead of disabled, so focus isn't lost and screen readers hear the state. Change the label too (“Saving”).
  • Icons are decorative; the label is the name. Icon-only buttons belong to the Icon Button component.
  • The tap target is at least 48px even at sm and xs (WCAG 2.5.8).

Do

  • Tab moves focus, Enter and Space press the button. Focus shows the Ritla ring: brand, or red with danger.
  • Keep a 48 px touch target; sm and xs get it from an invisible hit area.
  • Give icon-only actions a label through Icon Button.
  • Mark loading buttons as busy (aria-busy), which code does for you.

Don't

  • Remove or restyle the focus ring.
  • Rely on color alone to separate the main action; style and position carry it too.
  • Put two buttons closer than space-8 on touch screens.

Arabic and RTL notes

Mirrors

  • The leading icon sits at the inline start (right in Arabic) and the trailing one at the end, with no RTL prop.
  • Arrows and carets flip through <Icon>: “Next” points left in Arabic.
  • Action order mirrors: the main action is at the inline end in both directions.

Does not mirror

  • The loading spinner turns clockwise in both languages.
  • Checkmarks, download icons and logos inside buttons never mirror.
Numerals
Numbers inside a label (“Delete 3 files”) follow the numerals setting through formatNumber, not the button.
Arabic typography
Labels use body-16 (body-14 at xs) in Semibold; the button height is fixed and Arabic labels fit without clipping.
Mixed-direction text
A Latin name inside an Arabic label (“تسجيل الدخول باستخدام Google”) goes in <bdi> so punctuation doesn't jump.

Do

  • Use the RTL variant for every Arabic button, even without icons.
  • Swap directional icons to their RTL = Yes variant.
  • Leave room for Arabic labels, which often run longer than English ones.
  • Write numbers in labels with the numerals setting: ٣ عناصر or 3 items.

Don't

  • Type Arabic into the English variant: it keeps Geist and English line heights.
  • Mirror the spinner, checkmarks or logos.
  • Shorten an Arabic label into an abbreviation to fit a fixed width.

Checks it passes

The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.

  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)
  • R042Clipped text: content wider than its box with overflow hidden and no ellipsis
  • R043Fixed-pixel-width container whose Arabic text exceeds the space