Button

Button is a dynamic and interactive component that effortlessly enhances user engagement. With its intuitive design, it smoothly integrates into your interface, offering a seamless experience as users navigate and interact with your website or application.

Basic usage

Elemental buttons are native HTML <button> and <a> elements, styled according to the Docebo Design System guidelines.

Using native HTML elements ensures a simple and accessible experience. Use a <button> for actions that trigger changes or events, and an <a> for navigation that directs the user to a new view.

We employ a hierarchy of buttons to effectively guide user interactions and emphasize different actions within our applications. Each button variant can be applied as an attribute:

For example:

<button lmnButtonPrimary (trigger)="onConfirm()">Confirm</button>

<a lmnButtonTertiary href="/home-page">Go to home page</a>

Component anatomy

The Button component offers a comprehensive set of configurable options, styles, and states that enable it to adapt to various user interactions and design needs.

Theme

The Button component supports three main themes: Accent, Neutral and Danger. They can be applied by means of the theme input.

If not specified, the default theme is Neutral.

Content

The Button component supports flexible content options to accommodate various design and functional needs.

It can display a label, passed directly within the button as content projection, or an icon using the iconSvgName Input, where the icon's SVG name specifies the visual to be rendered.

For buttons that require both a label and an icon, the component allows a combined label + icon layout, with control over the icon’s positioning relative to the label. This positioning is managed via the iconPosition Input, which accepts "before" or "after" as values, enabling you to place the icon either before or after the label for optimal visual alignment.

Using all-uppercase labels in buttons can impact accessibility, particularly for users who rely on screen readers and those with visual or cognitive impairments.

Screen readers interpret text as it appears in the markup, so if the label is typed in all uppercase (e.g., "SUBMIT"), it may be read as individual letters rather than a single word. To avoid this, it’s recommended to keep the label text in standard case in the HTML and apply CSS (text-transform: uppercase;) to style the button visually.

Additionally, all-uppercase text can be harder for some users to read due to its uniform letter height, which can reduce legibility, especially for those with dyslexia or low vision. Using uppercase labels thoughtfully—avoiding long phrases and ensuring clear letter spacing—can help mitigate these concerns and improve the button’s readability and accessibility.

Shape

You can choose the shape of a Button by means of the shape Input, that allows you to select either a squared or rounded shape to suit different design contexts.

By setting shape="squared", the button will have sharp, right-angle corners, which can convey a more structured, precise look, often preferred in formal or data-centric interfaces.

Alternatively, setting shape="rounded" gives the button softly rounded corners, creating a friendlier, more approachable aesthetic that works well in casual or highly interactive designs.

If not specified, the default shape is squared.

Size

The Button component comes in five different sizes, catering to various layout requirements:

The size of a Button can be specified by means of the size input, whose accepted values are "xs", "sm", "md", "lg" or "xl".

If not specified, the default size is SM.

Width

The Button component is designed to adapt its width based on its content by default, expanding just enough to accommodate its label or icon.

However, if specific layout requirements call for a custom width, the button can also inherit an explicit width set externally, allowing it to fit seamlessly into various interface designs.

When constrained by a limited width, the Button automatically wraps its label text onto multiple rows to ensure all content remains visible. This responsive behavior helps maintain readability and usability, even in compact or variable-width layouts.

State

The Button component includes two externally configurable states, Loading and Disabled, which provide users with clear visual feedback and improve accessibility.

These states can be activated by simply passing the loading or disabled attributes, with the Loading state taking priority when both are applied simultaneously.

When the button is in the Disabled state, it remains keyboard focusable, allowing users to navigate to it, and a tooltip can be provided via the disabledTooltip Input to explain why the button is inactive.

In the Loading state, the button is also disabled but keyboard focusable, and displays a spinner to indicate that an action is in progress. You can specify a loadingTooltip to describe the ongoing process, offering additional context.

If the button displays only an icon (with no label), the disabledTooltip or loadingTooltip text is concatenated with the primary tooltip, resulting in a combined message such as "{tooltip} - {disabledTooltip}" or "{tooltip} - {loadingTooltip}" on hover or focus. This layered feedback keeps users informed about the button’s current state and its intended action, even when temporarily unavailable.

The Button component also supports an Active state, which is commonly used to visually indicate when a toggle button is selected.

This state can be activated by adding the active attribute to the button. When the button is in the Active state, it provides feedback to users by visually distinguishing it from unselected buttons. This is particularly useful in situations where the button’s state needs to be tracked, such as when selecting between options in a toggle or switch control. The Active state enhances interactivity and helps users clearly see which options are currently active or selected, contributing to a more intuitive user experience.

Accessibility

The Button component is designed with accessibility in mind, but certain practices are essential to make it truly accessible for all users. Follow these guidelines to ensure your Button implementation meets accessibility standards and provides a smooth experience for everyone.

Keyboard accessibility

The Button component remains focusable, even in Disabled and Loading states, allowing keyboard users to reach it and understand its status. It also provides a visible focus ring to help keyboard users track their position within the interface.

If you customize button styling, make sure the focus indicator is preserved so users navigating with a keyboard can clearly see when the button is focused.

Roles and states

The Button component is built on top of the native HTML <button> or <a> tags, and it does not automatically apply any ARIA role. As a result, you have the flexibility to specify the appropriate role based on the context in which the button is used, selecting from the roles supported by these native tags, such as button, link, or any other relevant role.

The Button component automatically adds aria-disabled="true" when in Disabled state, and aria-busy="true" when in Loading state, which screen readers interpret to indicate that the button is unavailable or busy.

However, if your button is disabled or loading, you should provide context with disabledTooltip or loadingTooltip text. This will clearly explain to users why the button is temporarily unavailable or in progress. The disabledTooltip/loadingTooltip message is automatically set as an aria-describedby attribute as well, so that screen readers perceive it as well; however, you can override the aria-describedby attribute if you want to convey an alternative message to screen reader users.

Furthermore, when in Active state, you should manually provide an aria-checked="true" or aria-selected="true" attribute, basing on the ARIA role of the button, so that screen readers perceive the active state as well.

Contrast and readability

While the Button component's default themes already meet the WCAG contrast ratio guidelines, always verify the required contrast (4.5:1 for regular text, 3:1 for large text) is maintained even when customizing the appearance of the Button. This ensures readability for users with visual impairments.

Furthermore, if you are using all-uppercase labels, apply text-transform: uppercase; in CSS instead of writing labels in uppercase directly. This helps screen readers interpret the label as a word rather than individual letters, providing a better experience for screen reader users.

Alternative text

For icon-only buttons, use a clear tooltip and aria-label to communicate the button’s purpose.

Error prevention for critical actions

If the button triggers irreversible or critical actions, consider adding a confirmation step (such as a dialog prompt) to prevent accidental clicks. This can be especially useful for users with motor disabilities who may accidentally trigger buttons.