Button
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
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add buttonAlso works with shadcn:
npx shadcn@latest add @ritla/buttonDependencies it brings
@base-ui/react@phosphor-icons/reactOr 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
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.
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.
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.
Icons
iconLeading and iconTrailing are optional. “Next” uses ArrowRightIcon in both languages and flips in Arabic to point forward; the download icon never mirrors.
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.
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”.
As a link
Navigation stays a link even when it looks like a button: pass render={<a href=… />} or Next's <Link>. It takes the Button's look and stays a link for screen readers.
API reference
Button
Any other Base UI Button prop passes through (onClick, type…).
| Prop | Type | Default | Description |
|---|---|---|---|
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. |
danger | boolean | false | Figma's Danger: red for destructive actions, with a red focus ring. |
children | ReactNode | None | Figma's Label: the button text. |
iconLeading | IconComponent | None | Icon leading: a Phosphor or Ritla UI icon at the inline start. |
iconTrailing | IconComponent | None | Icon 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. |
loading | boolean | false | State = Loading: spinner in the leading slot, aria-busy, the button stays focusable and ignores presses. |
disabled | boolean | false | State = Disabled. |
render | ReactElement | None | Another element with the Button look, usually a link (<a> or <Link>). It keeps its own semantics, so it isn't announced as a button. |
className | string | None | Extra 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. Touch target
size/touch-targetThe outer frame: at least 48 px tall in every size.
smandxsadd it without taking layout space.2. Content
variant, dangerFill and stroke follow Style;
radius/10atlg,radius/8atmd,radius/6atsm,radius/4atxs.3. Leading icon
iconLeading24 at
lg, 20 atmd,smandxs. Sits at the inline start.4. Label
childrenThe Label text property:
body-16/Semibold,body-14/Semiboldatxs.5. Trailing icon
iconTrailingSame sizes as the leading icon. Sits at the inline end and mirrors in RTL.
6. Loading indicator
loadingReplaces the leading icon while pending; the label stays so the width does not jump.
7. Focus ring
2 px ring on
focus-visibleonly, 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.
| Style | How many | Use for |
|---|---|---|
filled | One per view | The main action of the view: Save, Send, Pay, Create. |
tonal | One or two | A strong secondary action that should stay visible next to the main one. |
outline | As needed | Alternatives to the main action: Cancel, Back, Skip. |
ghost | As needed | Low-emphasis actions inside content, cards and toolbars. |
inverted-ghost | As needed | Actions on brand or dark surfaces: banners, hero sections, the inverse toast. |
danger | One, at the end of a flow | Destructive 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.
inverted-ghostWhite text on a translucent fill keeps contrast on brand blue.ghost on brandGray text on brand blue fails contrast and looks disabled.Do
- Give each view one
filledbutton for its main action. - Use
inverted-ghoston brand and dark surfaces. - Keep the same style for the same action across the product.
Don't
- Put two
filledbuttons side by side. - Use
ghostoroutlineon 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
- 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
- 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
- Use one size for every button in a group.
- Leave at least
space-8betweensmandxsbuttons 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
xsas 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
- 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
- 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.
outline or ghost with danger on the page; filled with danger only in the confirmation.Do
- Name what is lost: Delete project.
- Use
outlineorghostwithdangeron the page, andfilledwithdangeronly 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.
8. Buttons and links
A button does something; a link goes somewhere. When a link needs the look of a button (“Get started” on a landing page), keep it a link in code with render={<a href>} so screen readers announce it as a link and it can open in a new tab.
Do
- Use a Button for actions on the current page.
- Use a link with the Button look for navigation to another page.
- Use the Link component inside running text.
Don't
- Use a Button to navigate between pages without link semantics.
- Style a link as a
filledbutton inside a paragraph.
Before handoff
- One
filledbutton 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
dangerand 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).
| Size | Height, padding, gap, radius | Label and icons |
|---|---|---|
lg | 56 · space-24 · space-8 · radius/10 | body-16/Semibold · 24 |
md | 48 · space-24 · space-8 · radius/8 | body-16/Semibold · 20 |
sm | 40 · space-16 · space-8 · radius/6 | body-16/Semibold · 20 |
xs | 32 · space-12 · space-8 · radius/4 | body-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.
| Style | Fill and border | Label |
|---|---|---|
filled | background/brand/solid | text/brand/on-brand |
filled · danger | background/danger/solid | text/static/white |
tonal | background/brand/faint | text/brand/subtle |
tonal · danger | background/danger/faint | text/danger/subtle |
outline | background/surface/lowest · border/gray/soft | text/gray/subtle |
outline · danger | background/surface/lowest · border/danger/soft | text/danger/subtle |
ghost | alpha/tint-12 | text/gray/subtle |
ghost · danger | alpha/tint-12 | text/danger/subtle |
inverted-ghost | alpha/tint-12 | text/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.
| Key | Action |
|---|---|
| Tab | Moves focus to the button and shows the focus ring (red with danger). |
| EnterSpace | Activates it. While loading, focus stays and the action doesn't repeat. |
ARIA
- A native
<button>(or<a>withrender), so noroleis needed. - Loading sets
aria-busy="true"andaria-disabled="true"instead ofdisabled, 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
smandxs(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;
smandxsget 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-8on 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-14atxs) 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.
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space