dile-button

Web Component to create a customizable button.

Installation

npm i @dile/ui

Usage

Import the dile-button component.

import '@dile/ui/components/button/button.js';

Use the component.

<dile-button>Button Label</dile-button>

Adding an icon

dile-button can display an icon next to (or instead of) its label, using the same "family.name" string format as dile-iconlib. If you don't set the icon property the component renders a plain text button with no icon.

The icon glyph is imported separately, just like with dile-iconlib:

import '@dile/ui/components/button/button.js';
import '@dile/iconlib/lucide-icons/rocket.js';

<dile-button icon="lucide.rocket">Launch app</dile-button>

Supported icon families are the ones documented in dile-iconlib: lucide, material, fontawesome, phosphor, tabler and remixicon.

If you already build the icon as a lit-html template or an <img> template (instead of a "family.name" string), use dile-button-icon instead.

Properties

• disabled: Boolean, mark button as disabled.
• loading: Boolean, shows a loading spinner and prevents interaction while loading.
• name: The name of the button. It reflects to the name attribute, so it is sent correctly on native <form> submission, even if you set it from JavaScript instead of markup.
• value: The value submitted for this button's name when it is the button that triggers the form submission, mirroring a native <button type="submit" name="..." value="...">.
• type: Use this attribute to create a submit or reset buttom, ie: type="submit"
• icon: String in "family.name" format (e.g. "lucide.rocket", "material.star"). When empty, no icon is rendered and the button works like a plain text button.
• iconPosition: "left" (default) or "right" (attribute icon-position). Sets where the icon appears relative to the label.
• no-wrap: Boolean, prevents the label from wrapping into several lines.
• label: String used as the button's accessible name (aria-label). Required for icon-only buttons (no slotted text), otherwise the button has no accessible name.

When type="submit", clicking the button submits its closest ancestor <form> and includes its name/value pair in the submitted data — only for the button that was actually clicked, so you can safely use several submit buttons with different name/value pairs in the same form to distinguish which action was triggered.

Accessibility notes

• The inner dile-iconlib icon is marked aria-hidden="true" because it is decorative; the accessible name comes from the slotted text or from the label property.
• The native focus ring (--dile-button-ring-color) is preserved for keyboard users.

CSS Custom Properties

You can customize it using CSS Custom Properties.

The component accepts both the older --dile-button-* aliases and the more generic --dile-primary-* variables. Alias variables take precedence; when not provided the component falls back to the generic variables and then to the built-in defaults.

The following properties apply when the button has an icon (they are shared with dile-button-icon):

dile-button demos

Regular button

<dile-button>Click here!</dile-button>

Styled button

<style>
  .styled {
    --dile-button-border-color: #666;
    --dile-button-hover-border-color: #ff910f;
    --dile-button-background-color: #491449;
    --dile-button-hover-background-color: #f3c6f3;
    --dile-button-text-color:  #fff; 
    --dile-button-hover-text-color:  #000; 
    --dile-button-font-weight: bold;
    --dile-button-ring-color: #cc5099;
    --dile-button-ring-offset-width: 2px;
    --dile-button-border-radius: 4px;
    --dile-button-text-transform: uppercase;
  }
</style>
<dile-button class="styled">Click here!</dile-button>

Disabled button

  <dile-button name="disabeldbutton" disabled id="disabeldbutton">Disabled button</dile-button>

Loading button

  <dile-button name="loadingbutton" loading id="loadingbutton">Loading...</dile-button>

Button with an icon

The icon glyph is imported separately, exactly like with dile-iconlib.

<script type="module">
  import '@dile/iconlib/lucide-icons/rocket.js';
  import '@dile/iconlib/lucide-icons/arrow-right.js';
  import '@dile/iconlib/lucide-icons/heart.js';
  import '@dile/iconlib/lucide-icons/settings.js';
</script>
<dile-button icon="lucide.rocket">Launch app</dile-button>

Icon on the right

<dile-button icon="lucide.arrow-right" icon-position="right">Continue</dile-button>

Icon-only button

An icon-only button needs a label for its accessible name.

<dile-button icon="lucide.settings" label="Open settings"></dile-button>