Skip to content

Latest commit

 

History

History
263 lines (212 loc) · 12.5 KB

README.md

File metadata and controls

263 lines (212 loc) · 12.5 KB
Raw

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>

Best Practices

  • Use buttons to cause an action or launch a workflow
  • Keep button 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

Button [d2l-button]

The d2l-button element can be used just like the native button element, but also supports the primary attribute for denoting the primary button.

<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]

The d2l-button-subtle element can be used just like the native button, but for advanced or de-emphasized actions.

Note: It is strongly recommended to use text and icon as opposed to putting content in the slot to ensure that the recommended subtle button style is maintained.

<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) or text. If text, aligns the button content to the leading 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]

The d2l-button-icon element can be used just like the native button, for instances where only an icon is displayed.

<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) or text. If text, aligns the button content to the leading 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]

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.

<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

Add Button [d2l-button-add]

The d2l-button-add is for quickly adding new items at a specific location, such as when adding items to a curated list. Since the Add button is meant to be subtle, it should always be used in combination with more obvious methods to add items (like a menu or primary button).

<script type="module">
  import '@brightspace-ui/core/components/button/button-add.js';
</script>
<d2l-button-add text="Add New Item"></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).

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.

The best time to use floating workflow buttons is when users need immediate access to the buttons without scrolling. 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.

<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 aria-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!