Name	Name	Last commit message	Last commit date
parent directory ..
demo	demo
test	test
README.md	README.md
button-add.js	button-add.js
button-copy-mixin.js	button-copy-mixin.js
button-copy.js	button-copy.js
button-icon.js	button-icon.js
button-mixin.js	button-mixin.js
button-move.js	button-move.js
button-split-item.js	button-split-item.js
button-split.js	button-split.js
button-styles.js	button-styles.js
button-subtle-copy.js	button-subtle-copy.js
button-subtle.js	button-subtle.js
button-toggle.js	button-toggle.js
button.js	button.js
floating-buttons.js	floating-buttons.js

Buttons

A Button is used to communicate and perform an action.

<script type="module">
  import '@brightspace-ui/core/components/button/button.js';
  import '@brightspace-ui/core/components/button/button-subtle.js';
  import '@brightspace-ui/core/components/button/button-icon.js';
</script>
<d2l-button>Button</d2l-button>
<d2l-button primary>Primary Button</d2l-button>
<d2l-button-subtle text="Subtle Button" icon="tier1:gear"></d2l-button-subtle>
<d2l-button-icon text="Icon Button" icon="tier1:gear"></d2l-button-icon>

Button [d2l-button]

Use a Button for most actions, especially if they need to be obvious to the user. For the main action on the page, use the primary attribute to draw the user's attention.

Best Practices

Use buttons to cause an action or launch a workflow
Keep text short - see "Writing" guidelines

Don't use multiple Primary buttons - the primary action should always be clear and obvious
Avoid icon-only buttons with unfamiliar icons, only use these for familiar concepts
Don't use buttons for navigation, use a link instead
Don't open menus with buttons - use a dropdown instead

<script type="module">
  import '@brightspace-ui/core/components/button/button.js';
</script>
<d2l-button>My Button</d2l-button>

Properties

Property	Type	Description
`description`	String	A description to be added to the `button` for accessibility for additional context
`disabled`	Boolean	Disables the button
`disabledTooltip`	String	Tooltip text when disabled
`primary`	Boolean	Styles the button as a primary button

Subtle Button [d2l-button-subtle]

Use subtle buttons for secondary, advanced, or de-emphasized actions that should not compete with primary tasks.

Best Practices

Include an icon if you want to draw attention to the action or improve recognition
Keep subtle button text short - see [Writing guidelines]({{ project.assetPath }}/style-elements/writing/)

Don’t put content in the slot to set the visible label or icon; use text or icon to ensure styles are maintained
Don’t use subtle buttons for primary or destructive actions — reserve them for less prominent interactions
Don't use subtle buttons for navigation, use a link instead
Don't open menus with subtle buttons - use a dropdown instead

<script type="module">
  import '@brightspace-ui/core/components/button/button-subtle.js';
</script>
<d2l-button-subtle text="My Button" icon="tier1:gear"></d2l-button-subtle>

Properties

Property	Type	Description
`text`	String, required	Text for the button
`description`	String	A description to be added to the `button` for accessibility for additional context
`disabled`	Boolean	Disables the button
`disabledTooltip`	String	Tooltip text when disabled
`h-align`	String	Possible values are undefined (default), `text` or `text-end`. If `text` or `text-end`, aligns the button content to the leading (or trailing) edge of text.
`icon`	String	Preset icon key (e.g. `tier1:gear`)
`icon-right`	Boolean	Render the icon on the right of the button

Subtle Button with Custom Icon

<script type="module">
  import '@brightspace-ui/core/components/button/button-subtle.js';
  import '@brightspace-ui/core/components/icons/icon-custom.js';
</script>
<d2l-button-subtle text="Subtle Button">
  <d2l-icon-custom slot="icon">
    <svg xmlns="http://www.w3.org/2000/svg" mirror-in-rtl="true">
      <path fill="#494c4e" d="M18 12v5a1 1 0 0 1-1 1H1a1 1 0 0 1-1-1v-5a1 1 0 0 1 2 0v4h14v-4a1 1 0 0 1 2 0z"/>
      <path fill="#494c4e" d="M13.85 3.15l-2.99-3A.507.507 0 0 0 10.5 0H5.4A1.417 1.417 0 0 0 4 1.43v11.14A1.417 1.417 0 0 0 5.4 14h7.2a1.417 1.417 0 0 0 1.4-1.43V3.5a.47.47 0 0 0-.15-.35zM7 2h1a1 1 0 0 1 0 2H7a1 1 0 0 1 0-2zm4 10H7a1 1 0 0 1 0-2h4a1 1 0 0 1 0 2zm0-4H7a1 1 0 0 1 0-2h4a1 1 0 0 1 0 2z"/>
    </svg>
  </d2l-icon-custom>
</d2l-button-subtle>

Icon Button [d2l-button-icon]

Use icon buttons for compact, supplementary actions where space is limited and the action is visually represented by a familiar icon.

Best Practices

Ensure the icon is clear, simple, and universally recognized for its intended action — avoid complex or ambiguous icons

Don’t use icon-only buttons for critical or primary actions; pair with text if the action is essential or not universally understood
Don’t use icons that are unfamiliar, decorative, or easily confused with other actions — stick to established conventions
Don’t overload interfaces with too many icon buttons — maintain a clear hierarchy and avoid visual clutter
Don't use icon buttons for navigation, use a link instead
Don't open menus with icon buttons - use a dropdown instead

<script type="module">
  import '@brightspace-ui/core/components/button/button-icon.js';
</script>
<d2l-button-icon text="My Button" icon="tier1:gear"></d2l-button-icon>

Properties

Property	Type	Description
`description`	String	A description to be added to the `button` for accessibility for additional context
`icon`	String, required	Preset icon key (e.g. `tier1:gear`)
`text`	String, required	Accessible text for the button
`disabled`	Boolean	Disables the button
`disabledTooltip`	String	Tooltip text when disabled
`h-align`	String	Possible values are undefined (default), `text` or `text-end`. If `text` or `text-end`, aligns the button content to the leading (or trailing) edge of text.
`translucent`	Boolean	Indicates to display translucent (ex. on rich backgrounds)

Icon Button with Custom Icon

<script type="module">
  import '@brightspace-ui/core/components/button/button-icon.js';
  import '@brightspace-ui/core/components/icons/icon-custom.js';
</script>
<d2l-button-icon text="Custom Icon Button">
  <d2l-icon-custom slot="icon">
    <svg xmlns="http://www.w3.org/2000/svg" mirror-in-rtl="true">
      <path fill="#494c4e" d="M18 12v5a1 1 0 0 1-1 1H1a1 1 0 0 1-1-1v-5a1 1 0 0 1 2 0v4h14v-4a1 1 0 0 1 2 0z"/>
      <path fill="#494c4e" d="M13.85 3.15l-2.99-3A.507.507 0 0 0 10.5 0H5.4A1.417 1.417 0 0 0 4 1.43v11.14A1.417 1.417 0 0 0 5.4 14h7.2a1.417 1.417 0 0 0 1.4-1.43V3.5a.47.47 0 0 0-.15-.35zM7 2h1a1 1 0 0 1 0 2H7a1 1 0 0 1 0-2zm4 10H7a1 1 0 0 1 0-2h4a1 1 0 0 1 0 2zm0-4H7a1 1 0 0 1 0-2h4a1 1 0 0 1 0 2z"/>
    </svg>
  </d2l-icon-custom>
</d2l-button-icon>

Toggle Button [d2l-button-toggle]

Use toggle buttons when users need to easily flip between two opposing states, such as when subscribing or unsubscribing.

The d2l-button-toggle element is a container for buttons that toggle a pressed state. The component will automatically show or hide the buttons and manage focus based on the pressed state. Simply place a d2l-button-icon or d2l-button-subtle element in each of the not-pressed and pressed slots. Each button should describe the state and action the user can take.

Best Practices

Use when flipping a setting on or off needs to be quick and easy, such as when users are expected to change the setting frequently

Don’t use toggle buttons for unrelated actions, navigation, or as form inputs — use checkboxes or radio buttons for form selection
Avoid ambiguous language — users shouldn't have to guess whether the toggle is giving the current state or describing an action it will perform

<script type="module">
  import '@brightspace-ui/core/components/button/button-subtle.js';
  import '@brightspace-ui/core/components/button/button-toggle.js';
</script>
<d2l-button-toggle pressed>
  <d2l-button-subtle slot="not-pressed" icon="tier1:lock-unlock" text="Unlocked" description="Click to lock."></d2l-button-subtle>
  <d2l-button-subtle slot="pressed" icon="tier1:lock-locked" text="Locked" description="Click to unlock."></d2l-button-subtle>
</d2l-button-toggle>

Properties

Property	Type	Description
`pressed`	Boolean	Pressed state

Events

d2l-button-toggle-change: dispatched when the pressed state changes

Split Button [d2l-button-split]

Use a split button when you need to group a main action with a set of closely related alternative actions, especially when space is limited.

The d2l-button-split element provides a main button and a slot for d2l-button-split-item elements. Simply provide a key and text for the main button and each item. The d2l-button-split's click event provides the key of the selected action.

Best Practices

Make the main action the most common action the user takes, while the related actions are similar but less popular or prominent actions
- For example, a "Save" button with additional options like "Save As" or "Save and Close"
Keep split button text short - see [Writing guidelines]({{ project.assetPath }}/style-elements/writing/)

Don’t use split buttons for unrelated or mutually exclusive actions
Don’t use split buttons as a replacement for navigation or for actions that should be separate, standalone buttons
Avoid including more than 5 actions
Don’t use split buttons excessively or in groups; reserve them for cases where the pattern adds real value
Don’t use split buttons if there is enough space to show all actions, since the Split Button requires user interaction to reveal hidden options

<script type="module">
  import '@brightspace-ui/core/components/button/button-split.js';
  import '@brightspace-ui/core/components/button/button-split-item.js';
</script>
<d2l-button-split key="save" text="Save" primary>
  <d2l-button-split-item key="saveAsDraft" text="Save as Draft"></d2l-button-split-item>
  <d2l-button-split-item key="saveAndClose" text="Save and Close"></d2l-button-split-item>
  <d2l-button-split-item key="saveAndNew" text="Save and New"></d2l-button-split-item>
</d2l-button-split>

Properties

Property	Type	Description
`description`	String	A description to be added to the main button for accessibility for additional context
`disabled`	Boolean	Disables the main button and menu opener
`disabledTooltip`	String	Tooltip text when disabled
`key`	String, required	Key of the main button, provided on the `click` event detail
`primary`	Boolean	Styles the main button and menu opener as primary buttons
`text`	String, required	Accessible text for the main button

Item Properties

Property	Type	Description
`disabled`	Boolean	Disables the menu item
`key`	String, required	Key of the menu item, provided on the `click` event detail
`text`	String, required	Accessible text for the menu item

Events

click: dispatched when the user clicks the main action or menu item. The key is provided on the event detail.

Add Button [d2l-button-add]

Use the Add button when users need to quickly insert new items at specific locations within a curated list or collection.

Best Practices

Place the button where users expect to add items, such as between list elements or at logical insertion points between page sections

Don’t use the add button as the only method for adding items — always supplement with a more prominent method (such as a main “Add” button or menu option) since the Add button is subtle and may not be discovered by all users
Don’t crowd the interface with too many add buttons; use them only where inline addition is helpful and contextually relevant

<script type="module">
  import '@brightspace-ui/core/components/button/button-add.js';
</script>
<d2l-button-add></d2l-button-add>

Properties

Property	Type	Description
`text`	String, required	The text associated with the button. When mode is "icon-and-text", this text is displayed next to the icon. Otherwise this text is in a tooltip.
`mode`	String	Display mode of the component. Defaults to "icon" (plus icon is always visible). Other options are "icon-and-text" (plus icon and text are always visible), and "icon-when-interacted" (plus icon is only visible when hover or focus).

Copy Icon Button [d2l-button-copy]

Use the Copy button to enable users to copy a text value to the clipboard. The d2l-button-copy's click event provides the writeTextToClipboard method for writing the text to the clipboard.

<script type="module">
  import '@brightspace-ui/core/components/button/button-copy.js';
  document.querySelector('d2l-button-copy').addEventListener('click', e => {
    e.detail.writeTextToClipboard(document.querySelector('#to-copy').textContent);
  });
</script>
<span id="to-copy">Lorem ipsum dolor sit amet, consectetur adipiscing elit</span>
<d2l-button-copy></d2l-button-copy>

Properties

Property	Type	Description
`disabled`	Boolean	Disables the button

Copy Subtle Button [d2l-button-subtle-copy]

Use the Copy button to enable users to copy a text value to the clipboard. The d2l-button-subtle-copy's click event provides the writeTextToClipboard method for writing the text to the clipboard.

<script type="module">
  import '@brightspace-ui/core/components/button/button-subtle-copy.js';
  document.querySelector('d2l-button-subtle-copy').addEventListener('click', e => {
    e.detail.writeTextToClipboard(document.querySelector('#to-copy').textContent);
  });
</script>
<span id="to-copy">Lorem ipsum dolor sit amet, consectetur adipiscing elit</span>
<d2l-button-subtle-copy text="Copy text"></d2l-button-subtle-copy>

Properties

Property	Type	Description
`disabled`	Boolean	Disables the button
`description`	String	A description to be added to the button for accessibility when text on button does not provide enough context
`slim`	Boolean	Makes the button slimmer
`text`	String	Label text for the button

Floating Buttons [d2l-floating-buttons]

Floating workflow buttons <d2l-floating-buttons> cause buttons to float or 'dock' to the bottom of the viewport when they would otherwise be below the bottom of the viewport. When their normal position becomes visible, they will undock.

Best Practices

Use floating workflow buttons to keep important, contextually relevant actions accessible when their normal position would otherwise be out of view
- An example is a long or complex form page where it's common for users to make frequent isolated edits rather than sequentially completing the form
Limit the number of floating buttons to only the most essential actions to reduce clutter and cognitive load.
- Consider using a Split Button if there are several related actions (such as Save, Save As...)

Don’t use floating buttons for actions that are not critical or frequently needed; avoid floating buttons for secondary or rarely used actions

<script type="module">
  import '@brightspace-ui/core/components/button/floating-buttons.js';
  import '@brightspace-ui/core/components/button/button.js';
</script>
<!-- docs: start hidden content -->
<style>
  .d2l-typography p {
    margin: 0.5rem;
  }
  .content-placeholder {
    align-items: center;
    background-color: var(--d2l-color-regolith);
    border: 2px dashed lightgrey;
    border-radius: 8px;
    display: flex;
    height: 600px;
    justify-content: center;
    width: 100%;
  }
  .empty-space {
    height: 5rem;
  }
</style>
<!-- docs: end hidden content -->
<div class="content-placeholder d2l-body-compact">
  Scroll to unstick
</div>
<d2l-floating-buttons>
  <d2l-button primary>Primary</d2l-button>
  <d2l-button>Secondary</d2l-button>
</d2l-floating-buttons>
<div class="empty-space"></div>

Accessibility

Daylight buttons rely on standard button semantics to ensure a smooth experience for all assistive technologies, but there are a few interesting details to note:

If the button's context is implied by visual layout, then description can be used to add missing context
- Example: if multiple page sections have an Edit button relying on visual layout to indicate which section it edits, there could be extra information in the description to help differentiate the Edit buttons for non-sighted users
If expanding other content in a dropdown, use the Dropdown component; if building custom expand/collapse behaviour, be sure to use expanded and aria-haspopup attributes in accordance with best practices.
Disabled buttons are normally not focusable as per web standards, but if the disabled state needs explaining you can use disabled-tooltip to provide an explanation that appears in a tooltip via aria-describedby
For Icon Buttons where there is no visible label, text will be displayed in a tooltip
- If both text and aria-label are used, then aria-label will be used as the primary label while text will be used in a tooltip
Toggle buttons should describe the current state and the action the user can perform. As such, aria-pressed should not be used on the buttons as per W3C's Button Pattern.
- Example: "Unpinned, click to pin" and "Pinned, click to unpin"
Floating Buttons maintain their position in the document's structure, despite sticking to the bottom of the viewport, so the tab order is unaffected and the effect is imperceptible to screen reader users
- Be cautious when using always-float, since screen magnifier users may find it difficult to locate the buttons at the bottom of a large viewport

Future Improvements

<d2l-button-preset type="save"> for common button types that will have built-in language support

Looking for an enhancement not listed here? Create a GitHub issue!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

Buttons

Button [d2l-button]

Best Practices

Properties

Subtle Button [d2l-button-subtle]

Best Practices

Properties

Subtle Button with Custom Icon

Icon Button [d2l-button-icon]

Best Practices

Properties

Icon Button with Custom Icon

Toggle Button [d2l-button-toggle]

Best Practices

Properties

Events

Split Button [d2l-button-split]

Best Practices

Properties

Item Properties

Events

Add Button [d2l-button-add]

Best Practices

Properties

Copy Icon Button [d2l-button-copy]

Properties

Copy Subtle Button [d2l-button-subtle-copy]

Properties

Floating Buttons [d2l-floating-buttons]

Best Practices

Accessibility

Future Improvements

FilesExpand file tree

button

Directory actions

More options

Directory actions

More options

Latest commit

History

button

Folders and files

parent directory

README.md

Buttons

Button [d2l-button]

Best Practices

Properties

Subtle Button [d2l-button-subtle]

Best Practices

Properties

Subtle Button with Custom Icon

Icon Button [d2l-button-icon]

Best Practices

Properties

Icon Button with Custom Icon

Toggle Button [d2l-button-toggle]

Best Practices

Properties

Events

Split Button [d2l-button-split]

Best Practices

Properties

Item Properties

Events

Add Button [d2l-button-add]

Best Practices

Properties

Copy Icon Button [d2l-button-copy]

Properties

Copy Subtle Button [d2l-button-subtle-copy]

Properties

Floating Buttons [d2l-floating-buttons]

Best Practices

Accessibility

Future Improvements