Button

A form-aware button component for primary actions, event handling and consistent Monster styling.

Import

import { Button } from "@schukai/monster/source/components/form/button.mjs";

Source

View source code

Package

@schukai/monster

Since

1.0.0

click me!

Introduction

The Monster Button is the default control for primary, secondary and inline actions in forms, toolbars and simple call-to-action areas. Use it when you need a native button workflow with Monster styling, form association and predictable click handling.

When to use Button

Use it for direct actions: Submit forms, trigger dialogs, run local callbacks or provide lightweight toolbar actions.
Use it when styling must stay consistent: The component already follows Monster tokens, accessibility rules and button variants.
Use it when you need form-aware behavior: The control integrates with form semantics and can be focused, blurred or clicked programmatically.
Do not use it for API-driven command menus: If the button has to load actions first, use ApiButton instead.

Key Features

Form-aware control: Works as a proper button element with focus, blur, click and disabled handling.
Configurable labels and classes: Labels, CSS classes and ripple behavior can be set through documented options.
Accessible by default: The component keeps button semantics and supports ARIA configuration where needed.
Custom event support: Hook directly into configured actions or listen to monster-button-clicked.

Typical mistakes

Keep the Button simple. If the action opens a list of commands, fetches action metadata first or behaves like a command palette, switch to ActionButton or ApiButton. For styling, prefer Monster button classes and tokens over hardcoded colors or custom border radii.

Simple Button

This is a simple button example. It is a button with the text "click me!". Nothing more, nothing less.

click me!

Javascript

import "@schukai/monster/source/components/form/button.mjs";

HTML

<monster-button>click me!</monster-button>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Button With Event

This is a simple button example with click handling. It is a button with the text "click me!". When you click on the button, the text "Button clicked!" will be displayed below the button. The text will be removed after 2 seconds.

You can either attach a classic event handler to the element, or you can use the actions.click option.

click me!

Javascript

import "@schukai/monster/source/components/form/button.mjs";

HTML

<monster-button id="eeSh6A-button">click me!</monster-button>

<div id="eeSh6A-result" style="margin-top: 20px;display: flex;align-items: center;justify-content: center;">

</div>

<script>

    // watch for the DOMContentLoaded event
    window.addEventListener('DOMContentLoaded', function () {
        
        // get the button element and set a click event callback
        document.getElementById('eeSh6A-button').setOption("actions.click", function () {
            
            // set a text to the result element
            document.getElementById('eeSh6A-result').innerHTML = 'Button clicked!';
            
            // Reset the result after 2 seconds.
            // This is only there so that you can click more often.
            setTimeout(function () {
                document.getElementById('eeSh6A-result').innerHTML = '';
            }, 2000);
        });

    });

</script>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Component Design

This component is built using the Shadow DOM, which ensures its internal structure and styling are encapsulated. By using a shadow root, the button component remains isolated from external styles and scripts, protecting its layout and behavior from unintended modifications.

Shadow DOM and Accessibility

The encapsulation provided by the Shadow DOM prevents direct manipulation of the component's internal structure. This ensures consistency in both the button's design and behavior. Developers cannot access or override the button's internal elements directly but can utilize exposed parts for targeted styling.

Customizing Through Exported Parts

While the Shadow DOM isolates the component's internal structure, certain elements have been made customizable through exported parts. These parts allow developers to style specific aspects of the button component using CSS without compromising its encapsulation.

Available Part Attributes

control: Represents the button container, including its structure and layout.
button: Represents the button element itself, which can be styled for color, typography, and effects.

Below is an example of how to use CSS part attributes to customize the Button component.


monster-button::part(control) {
    display: inline-block;
    padding: 5px;
}

monster-button::part(button) {
    background-color: #007bff;
    color: #fff;
    border: none;
    border-radius: 4px;
    padding: 8px 16px;
    font-size: 14px;
    cursor: pointer;
}

monster-button::part(button):hover {
    background-color: #0056b3;
}

monster-button::part(button):disabled {
    background-color: #d6d6d6;
    color: #9a9a9a;
    cursor: not-allowed;
}

Explanation of the Example

monster-button::part(control): Styles the button container, ensuring spacing and alignment.
monster-button::part(button): Styles the button element with a background color, padding, and rounded corners.
monster-button::part(button):hover: Adds a hover effect to change the button's background color.
monster-button::part(button):disabled: Styles the button when it is in a disabled state, making it visually distinct.

Accessibility

The component supports accessibility best practices by ensuring that the button can be interacted with using keyboard navigation and screen readers. The aria-disabled attribute is automatically managed to reflect the button's state, and focus-related methods like focus() and blur() are provided to enhance usability.

HTML Structure

<monster-button></monster-button>

JavaScript Initialization

const element = document.createElement('monster-button');
document.body.appendChild(element);

Exported

Button

Derived from

CustomControl

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the CustomControl.

Option

Type

Default

Description

templates

object

Template definitions

templates.main

string

undefined

Main template

labels

object

Labels

labels.button

string

actions

object

Callbacks

actions.click

string

throw Error

classes

object

CSS classes

classes.button

string

monster-button-primary

disabled

boolean

false

effects

object

Effects

effects.ripple

boolean

true

type

string

button

havior of the button. Possible values are: submit, reset, button

aria

object

Aria attributes

aria.role

string

The role of the button, should only be set if the button is not a button

aria.label

string

click me!

since
deprecated

Properties and Attributes

The Properties and Attributes listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits Properties and Attributes from these parent classes. If you cannot find a specific Properties and Attributes in this list, we recommend consulting the documentation of the CustomControl.

data-monster-options: Sets the configuration options for the collapse component when used as an HTML attribute.
data-monster-option-[name]: Sets the value of the configuration option [name] for the collapse component when used as an HTML attribute.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the CustomControl.

State query methods

value()

Returns

{string}: value of the button

The current value of the button.

e = document.querySelector("monster-button");
console.log(e.value);

value(value)

Parameters

value {string}: value

Returns

{void}

Throws

{Error} unsupported type

Set the value of the button.

e = document.querySelector("monster-button");
e.value = 1;

Static methods

[instanceSymbol]()2.1.0

Returns

{symbol}

This method is called by the instanceof operator.

formAssociated()

Returns

{boolean}

getCSSStyleSheet()

Returns

{CSSStyleSheet[]}

getTag()

Returns

{string}

observedAttributes()

Returns

{string[]}

This method determines which attributes are to be monitored by attributeChangedCallback().

Lifecycle methods

Lifecycle methods are called by the environment and are usually not intended to be called directly.

[assembleMethodSymbol]()

Returns

{Button}

Other methods

blur()

The Button.blur() method removes focus from the internal button element.

click()3.27.0

The Button.click() method simulates a click on the internal button element.

focus(options)3.27.0

Parameters

options {object}: options

The Button.focus() method sets focus on the internal button element.

Events

The component emits the following events:

monster-button-clicked
this event is triggered when the button is clicked. It contains the field {button} with the button instance.

For more information on how to handle events, see the mdn documentation.

The current width of the area is too small to display the content correctly.