In progress

Button

A Button triggers an action or confirms a choice when the user activates it.

• Figma
• Storybook
• Edit this page
• Create a new issue

Code example

import { Button } from '@yleisradio/yds-components-react';

<Button text="Primary" />

Why to use

Buttons are used to execute actions in the interface: submitting a form, opening a modal, cancelling an operation, or performing add/remove actions. They stand out visually from surrounding content and guide the user’s attention to the most important actions. The button text must clearly communicate what happens when it is pressed (for example, “Next” or “Submit form”). It should typically start with a verb and use Title Case or sentence case consistently across the product.

When to use

Buttons are used when the user needs to perform an explicit action. They initiate tasks, submit information, confirm decisions, or open additional functionality. Use a button any time the user is expected to do something rather than simply navigate or view content.

Do

• Use a button when an action changes data, advances a task, or opens an interaction.
• Use the Primary button for the main action in a section or flow.
• Use Secondary and Text buttons for supporting or lower-priority actions.
• Disable a button only when the action cannot yet be performed — and provide guidance nearby.
• Use full-width buttons on mobile to improve tap targets and clarity.
• Keep button sizes consistent within a group.
• Use icon-only buttons only when they fit the interaction pattern, the icon is widely recognized, or space is limited.

Don’t

• Don’t use multiple Primary buttons in the same section — it dilutes the main action.
• Don’t use disabled buttons to explain why something can’t be done — use helper or error text instead.
• Don’t use a button for simple navigation — use a link.
• Don’t use very small button sizes as the default, especially on touch devices.
• Don’t use a button when the action is ambiguous or when a menu or link would serve the flow better.

Content Guidelines

Button labels must be short, clear, and action-oriented. They tell the user exactly what will happen when the button is pressed. Good labels increase confidence and reduce cognitive load.

Do

• Start labels with a clear verb (e.g., Tallenna, Jatka, Muokkaa, Poista).
• Keep labels brief — ideally 1–2 words.
• Use wording that clearly describes the result of the action (Luo tunnus, Lähetä palaute).
• Use consistent wording across the product (e.g., always use Peruuta for dismissing actions).
• Use icons only when they reinforce meaning, not replace it.
• Ensure icon-only buttons have an accessible name via aria-label.

Don’t

• Don’t use vague or generic labels like OK, Hyväksy, or Klikkaa tästä.
• Don’t include unnecessary words or politeness (Lähetä, kiitos!, Nyt voit tallentaa!).
• Don’t use long sentences — explanatory text belongs near the button, not inside it.
• Don’t use humor, jargon, or internal terminology unfamiliar to users.
• Don’t rely on icon-only labels without accessible text.
• Don’t write labels that imply uncertainty or lack of clarity (Ehkä myöhemmin, Kokeile tätä).

Anatomy

todo kuva

1. Container – Clickable target.
2. Label – Action text.
3. Optional Icon Left – Visual cue preceding text.
4. Optional Icon Right – Supplementary indicator.
5. Focus Ring – Visible outline on keyboard focus.
6. Disabled State – Reduced opacity and non-interactive.

Key Button Props

Use these props to configure the Button component.

text

Visible label text of the button. Explains the action performed when pressed.

Type	Example	Description
string		Text displayed inside the button that explains what happens when it is pressed.

Code example

<Button text="Submit" />

danger

Avoid using children for text because it may lead to inconsistent styling with some other props.

variant

Defines the visual and hierarchical level of the button.

Value	Example	Description
primary		Default variant for the main action.
secondary		Secondary action. Always used with a primary button.
text		Low-emphasis text-style button.

Code example

<Button text="Save" />
<Button variant="secondary" text="Cancel" />
<Button variant="text" text="Details" />

size

Adjusts dimensions and typography.

Value	Example	Description
xs		Smallest accessible button.
sm		Compact button.
md		Default size.
lg		Large button for key CTAs.

Code example

<Button size="xs" text="Button" />
<Button size="sm" text="Button" />
<Button size="md" text="Button" />
<Button size="lg" text="Button" />

isDisabled

Non-interactive, dimmed styling.

Type	Example	Description
boolean		Temporarily prevents user interaction. Sets aria-disabled on the button.

Code example

<Button isDisabled text="Submit" />

fullWidth

Expands Button to fill parent width – especially useful in mobile views.

Type	Example	Description
boolean		Makes the button stretch horizontally.

Code example

<div style={{ width: '300px' }}>
  <Button text="Button" fullWidth />
</div>

iconBefore

Adds icon component before the text.

Type	Example	Description
ReactNode		Rendered before the label text.

Code example

import { Play, ArrowRight } from '@yleisradio/yds-icons-react';

<Button iconBefore={<Play />} text="Play" />

iconAfter

Adds icon component after the text. Often used for dropdown indicators or directional arrows.

Type	Example	Description
ReactNode		Rendered after the label text.

Code example

import { ArrowRight } from '@yleisradio/yds-icons-react';

<Button text="Next" iconAfter={<ArrowRight />} />

iconOnly

Renders a button with only an icon, requires accessibleText for accessibility.

Type	Example	Description
boolean		Icon-only button variant.

Code example

<Button iconBefore={<Play />} accessibleText="Play media" iconOnly />

accessibleText

Supplementary text for screen readers when using icon-only buttons.

Type	Example	Description
string		Provides additional context for assistive technologies. Uses aria-label.

Code example

<Button text="Play" accessibleText="Play media" />

removePadding

Removes default padding, use only when you fully control the inner layout.

Type	Example	Description
boolean		Works only with variant="text". Eliminates default padding inside the button.

Code example

<Button text="Button" variant="text" removePadding />

loading

Replaces text with a loading spinner and disables interaction.

Type	Example	Description
boolean		Indicates that an action is in progress.

Code example

<Button text="Submit" loading />

Behavior

• Buttons change appearance based on interaction states (hover, focus, active, disabled, loading) to give clear feedback.
• Clicking or tapping a button should trigger its action immediately.
• Loading state should prevent repeated submissions or clicks.
• Disabled buttons should look inactive and not respond to interaction.
• Icon-only and dropdown buttons should provide the same interactive feedback as text buttons.
• Full-width buttons are recommended on mobile to improve tap targets and ergonomics.
• Buttons that open menus or dialogs should visually indicate their expanded or collapsed state.

Accessibility

• Disabled buttons should generally be focusable.
• Icon-only buttons must include accessible text via accessibleText.
• Fully keyboard-accessible and visible focus states.
  (WCAG 2.1.1 — Keyboard)

Implementation examples

Primary call-to-action

API Reference

Props

The Button component accepts all standard HTML <button> attributes in addition to the following props:

Prop	Type	Required	Default	Description
variant	'primary' | 'secondary' | 'text'	No	'primary'
isDisabled	boolean	No	false
iconBefore	React.ReactElement<SvgProps> | null	No	undefined
iconAfter	React.ReactElement<SvgProps> | null	No	undefined
iconOnly	boolean	No	false
loading	boolean	No	false
size	ButtonSize	No	'md'
text	string	No	—
accessibleText	string	No	—
fullWidth	boolean	No	false
removePadding	boolean	No	false

Type Definitions

export type ButtonSize = 'xs' | 'sm' | 'md' | 'lg';

export interface ButtonDSProps {
  variant?: 'primary' | 'secondary' | 'text';
  isDisabled?: boolean;
  iconBefore?: React.ReactElement<SvgProps> | null;
  iconAfter?: React.ReactElement<SvgProps> | null;
  iconOnly?: boolean;
  loading?: boolean;
  size?: ButtonSize;
  text?: string;
  accessibleText?: string;
  fullWidth?: boolean;
  removePadding?: boolean;
}

export type ButtonProps<C extends React.ElementType> = PolymorphicComponentPropsWithRef<
  C,
  ButtonDSProps
>;

Related Components

• Link – Navigational transitions.
• IconButton – Compact icon-only action surface.
• BannerNotification actions – Buttons embedded inside notifications.