Default Gray Amethyst

Button

<mo-button> | MOButton
Since 1.0 stable

Buttons trigger actions or events, such as submitting a form or opening a dialog.

Button 
<mo-button>Button</mo-button>

import { MOButton } from '@metsooutotec/modes-web-components/dist/react';

const App = () => <MOButton>Button</MOButton>;

Examples

Primary and secondary buttons

Use the primary and secondary variants to create regular buttons.

Primary Secondary 
<div >
  <mo-button variant="primary">Primary</mo-button>
  <mo-button variant="secondary">Secondary</mo-button>
</div>

import { MOButton } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <>
    <MOButton variant="primary">Primary</MOButton>
    <MOButton variant="secondary">Secondary</MOButton>
  </>
);

Subtle buttons

Use the subtle variant to create subtle buttons that share the same size as regular buttons but don’t have backgrounds or borders.

Text Text Text 
<mo-button variant="subtle" size="small">Text</mo-button>
<mo-button variant="subtle" size="medium">Text</mo-button>
<mo-button variant="subtle" size="large">Text</mo-button>

import { MOButton } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <>
    <MOButton variant="subtle" size="small">
      Text
    </MOButton>
    <MOButton variant="subtle" size="medium">
      Text
    </MOButton>
    <MOButton variant="subtle" size="large">
      Text
    </MOButton>
  </>
);

Sizes

Use the size attribute to change a button’s size.

Small Medium Large X-Large 
<mo-button size="small">Small</mo-button>
<mo-button size="medium">Medium</mo-button>
<mo-button size="large">Large</mo-button>
<mo-button size="x-large">X-Large</mo-button>

import { MOButton } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <>
    <MOButton size="small">Small</MOButton>
    <MOButton size="medium">Medium</MOButton>
    <MOButton size="large">Large</MOButton>
  </>
);

With only an icon

Buttons with only an icon and no text/label should have the attribute iconOnly enabled. The icon should go in the default slot as in the example below. 

<mo-button iconOnly variant="secondary" size="small"><mo-icon name="plus"></mo-icon></mo-button>
<mo-button iconOnly variant="secondary" size="medium"><mo-icon name="plus"></mo-icon></mo-button>
<mo-button iconOnly variant="secondary" size="large"><mo-icon name="plus"></mo-icon></mo-button>

It’s often helpful to have a button that works like a link. This is possible by setting the href attribute, which will make the component render as an <a> under the hood. This gives you all the default link behavior the browser provides (e.g. CMD/CTRL/SHIFT + CLICK) and exposes the target and download attributes.

Link New Window Download Disabled 
<mo-button href="https://example.com/">Link</mo-button>
<mo-button href="https://example.com/" target="_blank">New Window</mo-button>
<mo-button href="/assets/images/mo-logo.svg" download="modes-logo.svg">Download</mo-button>
<mo-button href="https://example.com/" disabled>Disabled</mo-button>

import { MOButton } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <>
    <MOButton href="https://example.com/">Link</MOButton>
    <MOButton href="https://example.com/" target="_blank">
      New Window
    </MOButton>
    <MOButton href="/assets/images/modes-logo.svg" download="modes-logo.svg">
      Download
    </MOButton>
    <MOButton href="https://example.com/" disabled>
      Disabled
    </MOButton>
  </>
);

Setting a custom width

As expected, buttons can be given a custom width by setting the width attribute. This is useful for making buttons span the full width of their container on smaller screens.

Small Medium Large 
<mo-button variant="primary" size="small" style="width: 100%; margin-bottom: 1rem;">Small</mo-button>
<mo-button variant="secondary" size="medium" style="width: 100%; margin-bottom: 1rem;">Medium</mo-button>
<mo-button variant="subtle" size="large" style="width: 100%;">Large</mo-button>

import { MOButton } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <>
    <MOButton variant="default" size="small" style={{ width: '100%', marginBottom: '1rem' }}>
      Small
    </MOButton>
    <MOButton variant="default" size="medium" style={{ width: '100%', marginBottom: '1rem' }}>
      Medium
    </MOButton>
    <MOButton variant="default" size="large" style={{ width: '100%' }}>
      Large
    </MOButton>
  </>
);

Prefix and suffix icons

Use the prefix and suffix slots to add icons.

Prefix Settings Suffix Refresh Both Open 
<div style="display: flex; flex-direction: column; gap: 16px; align-items: flex-start;">
  Prefix
  <mo-button variant="secondary">
    <mo-icon slot="prefix" name="settings"></mo-icon>
    Settings
  </mo-button>

  Suffix
  <mo-button variant="secondary">
    <mo-icon slot="suffix" name="refresh"></mo-icon>
    Refresh
  </mo-button>

  Both
  <mo-button variant="secondary">
    <mo-icon slot="prefix" name="ext-link"></mo-icon>
    <mo-icon slot="suffix" name="arrow-up"></mo-icon>
    Open
  </mo-button>
</div>

import { MOButton, MOIcon } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <>
    <MOButton variant="secondary" size="small">
      <MOIcon slot="prefix" name="settings"></MOIcon>
      Settings
    </MOButton>

    <MOButton variant="secondary" size="small">
      <MOIcon slot="suffix" name="refresh"></MOIcon>
      Refresh
    </MOButton>

    <MOButton variant="secondary" size="small">
      <MOIcon slot="prefix" name="ext-link"></MOIcon>
      <MOIcon slot="suffix" name="arrow-up"></MOIcon>
      Open
    </MOButton>
  </>
);

Loading

Use the loading attribute to make a button busy. The width will remain the same as before, preventing adjacent elements from moving around. Clicks will be suppressed until the loading state is removed.

Primary Secondary Subtle 
<div style="display: flex; flex-direction: row; gap: 16px">
  <mo-button variant="primary" loading>Primary</mo-button>
  <mo-button variant="secondary" loading>Secondary</mo-button>
  <mo-button variant="subtle" loading>Subtle</mo-button>
</div>

import { MOButton } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <>
    <MOButton variant="primary" loading>
      Primary
    </MOButton>
    <MOButton variant="secondary" loading>
      Secondary
    </MOButton>
    <MOButton variant="subtle" loading>
      Subtle
    </MOButton>
  </>
);

Disabled

Use the disabled attribute to disable a button. Clicks will be suppressed until the disabled state is removed.

Primary Secondary Subtle 
<div style="display: flex; flex-direction: row; gap: 16px">
  <mo-button variant="primary" disabled>Primary</mo-button>
  <mo-button variant="secondary" disabled>Secondary</mo-button>
  <mo-button variant="subtle" disabled>Subtle</mo-button>
</div>

import { MOButton } from '@metsooutotec/modes-web-components/dist/react';

const App = () => (
  <>
    <MOButton variant="default" disabled>
      Default
    </MOButton>

    <MOButton variant="primary" disabled>
      Primary
    </MOButton>

    <MOButton variant="success" disabled>
      Success
    </MOButton>

    <MOButton variant="neutral" disabled>
      Neutral
    </MOButton>

    <MOButton variant="warning" disabled>
      Warning
    </MOButton>

    <MOButton variant="alert" disabled>
      Alert
    </MOButton>
  </>
);

Styling buttons

This example demonstrates how to style buttons using a custom class. This is the recommended approach if you need to add additional variations. To customize an existing variation, modify the selector to target the button’s variant attribute instead of a class (e.g. mo-button[variant="primary"]).

Pink Button 
<mo-button class="pink">Pink Button</mo-button>

<style>
  mo-button.pink::part(base) {
    /* Set design tokens for height and border width */
    --mo-input-height-medium: 48px;
    --mo-input-border-width: 4px;

    border-radius: 0;
    background-color: #ff1493;
    border-top-color: #ff7ac1;
    border-left-color: #ff7ac1;
    border-bottom-color: #ad005c;
    border-right-color: #ad005c;
    color: white;
    font-size: 1.125rem;
    box-shadow: 0 2px 10px #0002;
    transition: var(--mo-transition-medium) transform ease, var(--mo-transition-medium) border ease;
  }

  mo-button.pink::part(base):hover {
    transform: scale(1.05) rotate(-1deg);
  }

  mo-button.pink::part(base):active {
    border-top-color: #ad005c;
    border-right-color: #ff7ac1;
    border-bottom-color: #ff7ac1;
    border-left-color: #ad005c;
    transform: scale(1.05) rotate(-1deg) translateY(2px);
  }

  mo-button.pink::part(base):focus-visible {
    outline: dashed 2px deeppink;
    outline-offset: 4px;
  }
</style>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Bundler React Script

To import this component using a bundler:

import '@metsooutotec/modes-web-components/dist/components/button/button.js';

To import this component as a React component:

import MOButton from '@metsooutotec/modes-web-components/dist/react/button/';

To import this component using a script tag:

<script type="module" src="https://modes-web.metso.com/dist/components/cdn/components/button/button.js"></script>

Slots

Name Description
(default) The button’s label.
prefix Used to prepend an icon or similar element to the button.
suffix Used to append an icon or similar element to the button.

Learn more about using slots.

Properties

Name Description Reflects Type Default
variant The button’s variant. 'docs' | 'primary' | 'secondary' | 'subtle' | 'header' 'primary'
size The button’s size. 'small' | 'medium' | 'large' | 'x-large' 'medium'
caret Draws the button with a caret for use with dropdowns, popovers, etc. boolean false
disabled Disables the button. boolean false
selected Draws button as selected for toggle button. boolean false
loading Draws the button in a loading state. boolean false
outline Draws an outlined button. boolean false
iconOnly Changes styling for buttons with only an icon. boolean false
open Adds open styling to button (see header menu). boolean false
type The type of button. When the type is submit, the button will submit the surrounding form. Note that the default value is button instead of submit, which is opposite of how native <button> elements behave. 'button' | 'submit' | 'reset' 'button'
name The name of the button, submitted as a name/value pair with form data, but only when this button is the submitter. This attribute is ignored when href is present. string ''
value The value of the button, submitted as a pair with the button’s name as part of the form data, but only when this button is the submitter. This attribute is ignored when href is present. string ''
href When set, the underlying button will be rendered as an <a> with this href instead of a <button>. string ''
target Tells the browser where to open the link. Only used when href is present. '_blank' | '_parent' | '_self' | '_top' -
rel When using href, this attribute will map to the underlying link’s rel attribute. Unlike regular links, the default is noreferrer noopener to prevent security exploits. However, if you’re using target to point to a specific tab/window, this will prevent that from working correctly. You can remove or change the default value by setting the attribute to an empty string or a value of your choice, respectively. string 'noreferrer noopener'
download Tells the browser to download the linked file as this filename. Only used when href is set. string | undefined -
form The “form owner” to associate the button with. If omitted, the closest containing form will be used instead. The value of this attribute must be an id of a form in the same document or shadow root as the button. string -
formAction
formaction 		Used to override the form owner’s action attribute. string -
formMethod
formmethod 		Used to override the form owner’s method attribute. 'post' | 'get' -
formNoValidate
formnovalidate 		Used to override the form owner’s novalidate attribute. boolean -
formTarget
formtarget 		Used to override the form owner’s target attribute. '_self' | '_blank' | '_parent' | '_top' -
validity Gets the validity state object - -
validationMessage Gets the validation message - -
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
mo-blur onMoBlur Emitted when the button loses focus. -
mo-focus onMoFocus Emitted when the button gains focus. -

Learn more about events.

Methods

Name Description Arguments
checkValidity() Checks for validity but does not show a validation message. Returns true when valid and false when invalid. -
getForm() Gets the associated form, if one exists. -
reportValidity() Checks for validity and shows the browser’s validation message if the control is invalid. -
setCustomValidity() Sets a custom validation message. Pass an empty string to restore validity. message: string
click() Simulates a click on the button. -
focus() Sets focus on the button. options: FocusOptions
blur() Removes focus from the button. -

Learn more about methods.

Parts

Name Description
base The component’s internal wrapper.
prefix The prefix container.
label The button’s label.
suffix The suffix container.
caret The button’s caret.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.