# Buttons {% hint style="info" %} This article is quite lengthy. To quickly find the information you're looking for, consider using the search. {% endhint %} ## Overview `Button` enable actions that are important to a user. They are not decorative elements. Instead, they direct users to complete important goals within an experience. * 1 `Button` = 1 action = 1 label * In most cases, `Buttons` are automatically displayed in a nested component such as `Page Title`, `Panel Header`, `Modal` , etc. ## Design Guidelines

Buttons are a central component for enabling users to take actions in our products. Roma offers a wide variety of buttons to better suit use-cases and interactions. ### Basic Buttons {% tabs %} {% tab title="Button" %} `Buttons` are highly visual clickable elements that are used to trigger actions. They allow users to interact with our product in various ways. `Button` is the main and most used one. **Async capabilities :**

`Loading state` creates a specific interaction. It must be used only when the action involve a back-end operation that may take some time. {% endtab %} {% tab title="Counter Button" %} `Counter Button` is to be used on very specific conditions. Because of its `Counter` props added after `Label`, this button is meant to trigger the action only on selected items. The user's selection automatically updates the counter. Users **have to** select at least 1 item before triggering action. Until then, `Counter Button` should remain disabled or hidden to emphasize its action perimeter. {% endtab %} {% endtabs %}

Deciding which button to use : Button / Async Button / Counter Button

*Click on the image to open it* These three buttons may look alike, but they display distinct behaviors based on the outcomes of their activation. `Button` is the default component. The action is direct, and does not need any loading.\ \&#xNAN;*exemple : A button "Create" opening a form ; a button "Close" to exit a modale* `Async Button` must be used only when the action involve a back-end operation that may take some time. It conveys the information to users back-end operation are ongoing.\ \&#xNAN;*exemple : A button "Save" to save an item creation form ; a button "Load more" to load list items* `Counter Button` must be used only when the action concerns pre selected items.

### Buttons with overlay {% tabs %} {% tab title="Menu Button" %} `Menu Button` allows presenting a large collection of actions to users without overloading the page content. The button triggers[`Action Menu`](https://design.mirakl.com/design/components/actions/action-menu) as an overlay. The final action is then triggered by the user's selection in the overlay. Because of our tool's various features, some pages may propose many actions. Not all of them need to be offered to users at once. While the most important actions must be highlighted by using [`Primary/Secondary Buttons`](https://design.mirakl.com/design/components/actions/buttons) and shown directly in the page content, other less important actions can be nested into a Menu Button. `Menu Button` has its guidelines and props. {% hint style="success" %} * Use Menu Button not to overload the page with too many small actions. * Follow Action Menu guidelines to display additional actions. {% endhint %} {% hint style="warning" %} * Do not hide important actions behind Menu Button because of low discoverability. {% endhint %} {% endtab %} {% tab title="Filter Button" %}

`Filter Button` should: * Always be used in a toolbar (e.g. for [Datatable](https://design.mirakl.com/design/components/datatable)) * Have the same microcopy as the column you wish to filter * Triggers a selection list `Filter Button` can also have a tooltip that appears when hovering the button. {% endtab %} {% tab title="Split Button" %} `Split Button` is a hybrid between a `Basic Button` and a `Menu Button` : it groups related commands into a dropdown but also offers one-click access to a default choice that does not require opening the menu. It has two components: a `Button` with a label and an `Icon Button` with an arrow. Clicking the `Button` triggers the default action - the most used one. Clicking on the `Icon Button` opens up a list of other minor possible actions related to the default one. Be careful when using `Split Button`. While it may seem like an obvious design pattern for some, options within the menu can have low discoverability for some users. In our research, we have found users don’t always recognize this pattern, so they may not notice the secondary menu button and, consequently, the options located within the menu. Therefore the default option should be strong enough to serve most use cases. We mostly use it in the [`Save Bar`](https://design.mirakl.com/design/components/actions/save-bar) to offer an additional "Save as Draft" option to forms. {% endtab %} {% endtabs %}

Deciding which button to use : Menu Button / Split Button

Those buttons are a great way to reduce visual clutter. However, they introduce more complexity into the design: the additional step results in a decrease in action discoverability. Use `Split Button` when you have one strongest action to propose compared to another one. For the user, clicking the main part triggers the primary action; clicking the right side reveals additional options. Use `Menu Button` for equally important but secondary actions, accessible after a click. For the user, clicking the button in itself doesn't trigger an action but it reveals additional options.

### Navigation Buttons {% tabs %} {% tab title="Navigation Button" %} Navigation Button is a button with an icon expliciting users they are going to navigate to another page Use `Navigation Button` for users to perform actions on another page. This component distinguishes itself from `Hyperlink` or `Link Button` by emphasizing its functionality, allowing users to perform actions rather than solely navigate.\ \&#xNAN;*exemple : Go to a configuration page related to current page's focus* {% endtab %} {% tab title="Link Button" %}

`Link Button` allows creating a visual hierarchy for those minor actions. They look like links but are not. `Link Button` is meant to be used sparingly. Some actions may not need to be as visually attractive as others. Those are *peripheral actions*. They bring added value to certain users in specific use cases, but yet those actions are still less important than others. `Link Button` comes in 2 sizes : `Small` or `Default`. It has 3 available states: `Primary`, `Secondary` and `Tertiary`. A customizable icon can be added before or after `Label` but it is not mandatory. It has to bring added value to understand the action. For example, adding a down arrow to the "See more" label help users understand some content is hidden but may be shown just below. {% hint style="success" %} Use the right size to comply with the page's homogeneity. {% endhint %} {% endtab %} {% endtabs %}

Deciding which button to use : Navigation Button / Link Button

Each of these components facilitates user navigation but with distinct objectives. Use `Link Button` for minor navigation options. While this component offer the possibility to users to navigate to another related page, they are not the primary focus of the page. `Link button` are meant to be used as secondary optional navigation.\ \&#xNAN;*exemple : Go back to previous page* Use `Navigation Button` to perform actions on another page. This component distinguishes itself from `Hyperlink` or `Link Button` by emphasizing its functionality, allowing users to perform actions rather than solely navigate.\ \&#xNAN;*exemple : Go to a configuration page related to current page's focus* Use Hyperlink to point to external resources, providing users with additional information or directing them to relevant documents or online resources, such as help center.\ \&#xNAN;*exemple : Learn more about a feature* #### When should I add a trailing icon to Navigation Button and Hyperlink ? Include an 'External link' icon when URL points to an external link (outside the current product). Users will be informed clicking on component will take them outside the current product. This transparency prevents confusion about whether they will remain within the current environment or navigate to an external source.\ Also, it enhances accessibility for users, especially those relying on screen readers or other assistive technologies. The 'External link' icon provides additional information about the nature of the link, aiding users with disabilities in understanding its context.

### Specific Use Cases Buttons {% tabs %} {% tab title="Icon Button" %} `Icon Button` are buttons with **no label**. It contains only a visual indication of the action it performs. Using `Icon Button` is a great way to stack multiple actions into a small space or to repeat the same action several times in the same view. Because only an icon is not easily understandable by everyone, **it must be used only for common actions,** such as `Download`, `Delete`, `View`, `Copy` , etc. For common actions, we must always use the same icon throughout our platform to facilitate our users' experience. `Icon buttons` can use `Primary`, `Secondary` or `Ghost` variant depending on the context. {% hint style="info" %} [Learn more about Icon Button on a Datatable](https://design.mirakl.com/components/datatable#55a556-2) {% endhint %} {% endtab %} {% tab title="Switch Button" %} Also known as "Toggle", `Switch Button` allows users to switch between two mutually-exclusive states, such as: * On/Off * Show/Hide * Activate/Deactivate {% hint style="info" %} Usually `Switch Button` is considered as a [selection control component](https://design.mirakl.com/design/components/form/selection-controls). However, we have decided to consider it a `Button` because it has an `Auto-Save` behavior, unlike other listed components in forms. {% endhint %} We mainly use `Switch Button` to swap between two views (Show/Hide elements). But it can also be used for use cases such as setting enablement (Activate/Deactivate). Because **its state cannot be indeterminate,**`Switch Button` always has a **default value**. It is up to product teams to determine which one would be the best one depending on features. #### Label and helptext This component can be used with or without a `Label`. The `Label` can be placed on the right or the left of the switch. Note that adding a `Label` is relevant to explain to users the concrete consequences of their actions. {% hint style="danger" %} Do not change Switch label depending on its state. The label must be understandable in both states. {% endhint %} If `Label` seems too short to explain the action's consequences, a`Helptext` prop can be added. Then, formatting is automated for the label to appear on the left and the switch component on the right.

If disabled, a `tooltip` appearing while hovering the component can be added to explain why the action is unavailable.

### Save pattern `Switch Button` has a generic autosave behavior, which means changes are saved without further actions from users. \ For critical changes, you may add a confirmation modal to make sure users understand what they are changing. {% hint style="warning" %} **Don't** use `Switch Button` in forms because of save pattern. Use checkboxes instead. {% endhint %} {% endtab %} {% tab title="Upload Button" %} `Upload Button` is a standard-looking button, but its behavior is restricted to file upload. It automatically handles file formatting and number acceptance. {% endtab %} {% endtabs %} ## ## Variations ### Variant

{% tabs %} {% tab title="Primary" %} Use a `Primary Button` to call the user's attention to the main action of a section or container. This variant is dedicated to strong and important actions. * `Primary Button` calls for important actions, it should be used mindfully. Our best guideline is to offer either a single `Primary Button` within the page title **or** one per container. * It must never be doubled up to sit side by side. * Not all pages require a `Primary Button`. Sometimes all actions are secondary to the content and of equal importance. {% endtab %} {% tab title="Secondary" %} Use a `Secondary Button` for additional and less important actions within a page. You can use several `Secondary buttons` on the same container, providing they serve the actual purpose of the feature. {% endtab %} {% tab title="Destructive" %} Use `Destructive Button` for actions that will delete or disable something important. {% hint style="danger" %} Destructive actions must be validated using a non-skippable confirmation modal. {% endhint %} {% endtab %} {% tab title="Ghost" %} Use for minor actions on a page. In main cases, `Ghost Button` goes with a `Primary button` for additional actions, such as “Cancel" or “Clear”. `Ghost Button` is used for minor actions that don't serve the actual purpose of the feature. {% hint style="info" %} If a button is placed within a page, it has to be included in a [spacing wrapper](https://design.mirakl.com/design/components/actions/broken-reference). {% endhint %} {% endtab %} {% endtabs %} ### ### Size

**In most cases, use Default Size.** The button height is set to 40px, but its width fits its content. Thus, be mindful when writing button microcopy. [Learn more on how to write labels for buttons](#content) The small size is reserved for tight spaces, such as `Datatable Toolbar`, `Panel Header`. The tiny size is dedicated to the tiniest spaces. {% hint style="info" %} What about the Stretch variant? `Button` has specific props:`Full width : True/False`. When activated, the button will fit the width of its container. It provides a Stretch effect. This prop is to be used sparingly, mostly for tiny spaces such as mobile or small containers. {% endhint %} ### State

Depending on users' interactions or action availability, buttons may be in various states * `Default state` is how buttons appear by default with no user interactions * `Hover state` is how buttons appear when the user moves their mouse over the component. While hovering, a `tooltip` may appear to provide more information about the action. * `Loading state` is how buttons interact when users click on the component, but the platform needs time to process the action. This interaction is mandatory when the button describes an action (creation, edition) and should not be used when the button creates a redirection. * `Disable state` is how buttons appear when the action is not clickable. Users will not be able to perform any action. A tooltip may appear to provide more information about the deactivation reasons. ## **Behaviors & Interactions** ### **Disable State or Hide Button?**

When an action is temporarily unavailable for reasons such as (but not only) : * Technical update ongoing * Roles allows a certain type of action, but a specific permission is required for an item Then, use `Disable state` to display the button without allowing user interaction. Also, provide context through tooltips. However, if the action is permanently inaccessible due to specific configurations such as (but not only) : * Roles don't allows actions at all Then, the button must be hidden. This way, the interface remains uncluttered and users are not presented with unnecessary options for them, reducing cognitive load and making the interface simpler to navigate. Hiding inaccessible buttons avoids confusion and frustration when users encounter non-functional elements. **Exemple :** \ As a user, I usually use a Button to perform a recurring action to an item. I know perfectly where this button is. But, it appear for once, i cannot perform this action as usual because the item status has changed. Thus, Button is in disable state with a tooltip to explain why I cannot perform this action as I usually do. But, if I didn't have the necessary permissions due to my role, I wouldn't have encountered this button previously.I would have never known about this action because I would have never had to perform it. ## Content Buttons are clear and predictable. They drive users to the next action. Capitalize the first word and don’t use punctuation {% hint style="info" %} Template: **\** or just **\** {% endhint %} {% hint style="success" %} Send message {% endhint %} Avoid unnecessary words and articles (’the’, ‘a’, ‘new’) {% hint style="success" %} Preview profile Import catalog {% endhint %} Reuse preexisting labels as much as possible, especially for common actions. It’ll help with adoption and scalability. {% hint style="success" %} Back, Continue, Delete {% endhint %} ## Accessibility {% hint style="info" %} All Button size are compliant to [WGAC 2.5.8 Minimum Target Size](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) {% endhint %} * In most cases, prefer using default-size buttons over small buttons. They are easier for users to notice and press.