MessageStateButton

Button component with integrated message display and state management

Import

import { MessageStateButton } from "@schukai/monster/source/components/form/message-state-button.mjs";

Source

View source code

Package

@schukai/monster

Since

2.11.0

click me!

Introduction

This is a versatile web component. More than just a simple UI element, this component serves as a key element for enhancing interactivity and engagement within various web applications. Whether you are developing a basic website or a complex enterprise-level application, this component is designed to improve user interaction and satisfaction.

Key Features

Dynamic interaction: Users can interact with content dynamically, making the web experience more intuitive and user-centric.
Customizable appearance: Customize the appearance of the component to match the design of your brand or application, ensuring visual consistency.
Accessibility: Designed with accessibility in mind to ensure that all users have a seamless experience, regardless of their browsing environment.
Visual feedback effect: Provides subtle touch feedback to enhance user interaction, making actions more responsive and engaging.
Programmatic Control: Offers methods such as trigger, focus, and deactivate, allowing developers to control the component's behavior programmatically and offering greater flexibility.

Improving the user experience

This component goes beyond its traditional functionality to offer an enhanced and interactive user experience. The combination of visual feedback effects and dynamic interaction with content is not only visually appealing, but also provides clear and responsive feedback to user actions, making the web environment more intuitive and user-friendly.

These improvements are supported by user studies that demonstrate a positive impact on user engagement and satisfaction.

Efficiency in the development process

Integrating this component into your development process is straightforward. Its compatibility with standard web technologies and ease of customization ensure seamless integration with your existing tools and libraries. Whether you're working on a small project or a large-scale application, the modular design of this component guarantees easy integration, streamlining your development process and enhancing productivity.

Message State Button Simple

Javascript

/** this example does not use an extra script **/

HTML

/** this example does not use an extra html file **/

Stylesheet

/** no additional stylesheet is defined **/

Component Design

The monster-message-state-button component combines a button with a dynamic message display system. It leverages the Shadow DOM to encapsulate its internal structure and styles, ensuring that the internal elements are isolated from the rest of the page.

This component includes a stateful button and a pop-up area (popper) for displaying messages. The encapsulation guarantees consistent styling and behavior, unaffected by external scripts or stylesheets.

Shadow DOM and Accessibility

The component uses the Shadow DOM to encapsulate its button, control container, and message elements. This ensures that external styles do not interfere with the component’s visual presentation. It also provides proper ARIA roles and attributes to support accessibility and usability.

Customizing Through Exported Parts

The monster-message-state-button component exposes its internal parts using the exportparts attribute. This allows developers to apply custom styles to specific parts of the component.

Available Part Attributes

control: Represents the main container for the button and message popper.
button: Styles the button element itself.
popper: Targets the message pop-up container, which appears when a message is displayed.
message: Represents the message content container inside the popper.
arrow: Targets the directional arrow displayed on the popper.

Below is an example of how to customize the component's parts using CSS:


monster-message-state-button::part(button) {
    background-color: #0078d4;
    color: #ffffff;
    padding: 8px 16px;
    border-radius: 4px;
    border: none;
    cursor: pointer;
}

monster-message-state-button::part(popper) {
    background-color: #f0f0f0;
    box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);
    padding: 12px;
    border-radius: 6px;
}

monster-message-state-button::part(message) {
    font-size: 14px;
    color: #333;
}

monster-message-state-button::part(arrow) {
    width: 12px;
    height: 12px;
    background-color: #f0f0f0;
    transform: rotate(45deg);
    margin-top: -6px;
}

Explanation of the Example

monster-message-state-button::part(button): Customizes the button's appearance, including background color, padding, and border radius.
monster-message-state-button::part(popper): Styles the popper container with a light background and box shadow.
monster-message-state-button::part(message): Defines the font and color for the message content.
monster-message-state-button::part(arrow): Adjusts the size and orientation of the directional arrow.

Accessibility

The component is designed to be accessible, supporting keyboard navigation and screen readers. It includes the following accessibility features:

Proper ARIA roles for the button and message elements.
Keyboard focus management for the button and popper.
Logical and semantic structure for screen readers to interpret messages.

Developers can further enhance accessibility by ensuring meaningful message content and labels.

HTML Structure

<monster-message-state-button></monster-message-state-button>

JavaScript Initialization

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

Exported

MessageStateButton

Derived from

Popper

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 Popper.

Option

Type

Default

Description

templates

object

Template definitions

templates.main

string

undefined

Main template

message

object

Message definition

message.content

string|htmlelement

undefined

The message content

message.title

string

undefined

The message title

message.icon

string

undefined

The message icon

mode

string

manual

The mode of the button, can be `manual` or `submit`

labels.button

string

Button label

features.disableButton

boolean

false

Disable the button

aria

object

Aria attributes

aria.role

string

Aria role, only if the button is not a button

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 Popper.

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 Popper.

Behavioral methods

clearMessage()

Returns

{MessageStateButton}

clears the Message

hideMessage()

Returns

{MessageStateButton}

removeState()

Returns

{MessageStateButton}

showDialog()

Returns

{MessageStateButton}

With this method, you can show the popper.

showMessage(timeout)

Parameters

timeout {number}: - Optional time in milliseconds after which the message will auto-hide

Returns

{messagestatebutton}: the button instance for chaining

Shows the message popup overlay with optional auto-hide timeout

toggleMessage()

Returns

{MessageStateButton}

Structural methods

getMessage()

Returns

{Object}

getState()

Returns

{MessageStateButton|undefined}

setMessage(message,title,icon)

Parameters

message {string|htmlelement}: - The message content as string or HTML element
title {string}: - Optional title to show above the message
icon {string}: - Optional icon HTML to display next to the title

Returns

{messagestatebutton}: the button instance for chaining

Throws

{TypeError} When message is empty or invalid type

Sets the message content to be displayed in the popup overlay

setState(state,timeout)

Parameters

state {string}: - The state to set (e.g. 'success', 'error', 'loading')
timeout {number}: - Optional timeout in milliseconds after which state is removed

Returns

{messagestatebutton}: the button instance for chaining

Throws

{TypeError} When state is not a string or timeout is not a number

Sets the state of the button which affects its visual appearance

Static methods

[instanceSymbol]()

Returns

{symbol}

This method is called by the instanceof operator.

getCSSStyleSheet()

Returns

{CSSStyleSheet[]}

getTag()

Returns

{string}

Lifecycle methods

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

[assembleMethodSymbol]()

Returns

{void}

Other methods

blur()

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

click()3.27.0

Events

monster-click

Programmatically triggers a click event on the button Will not trigger if the button is disabled

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-state-changed
Fired when button state changes
monster-message-shown
Fired when message is displayed
monster-message-hidden
Fired when message is hidden
monster-click
Fired when button is clicked
monster-click

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.