Metric

A metric display for one key number with compact labeling and status-oriented emphasis.

Import

import { Metric } from "@schukai/monster/source/components/data/metric.mjs";

Source

View source code

Package

@schukai/monster

Since

4.11.0

Introduction

The Monster Metric component highlights one important value in a compact visual form. Use it when a dashboard or summary view should emphasize a single number without the weight of a full chart.

When to use Metric

Use it for headline numbers: Revenue, users, conversions or error counts are typical examples.
Use it when comparison is secondary: The component focuses on the current value first.
Do not use it for trend-heavy stories: If historical movement matters, a graph or richer KPI element is often stronger.

Metric Simple

This is a monster-metric control configured to show quarterly customer growth. The main value “142 Customers” represents the current number of new customers in Q1. A change value of “+21.4 %” is displayed with a directional arrow rotated 30°, indicating positive growth compared to the previous year.

The change is styled using the class positive, which typically applies green coloring and an upward trend indicator. The label “New Customers Q1” is used as a title, while “Q1 Last Year” appears as subtext with a secondary value of “117 Customers” shown below it.

This setup provides a quick visual summary of performance over time, ideal for dashboards and reports.

Javascript

//import '@schukai/monster/source/components/data/metric.mjs';<script type="module">//import '@schukai/monster/source/components/data/metric.mjs';</script>

HTML

<monster-metric
        data-monster-option-values-main="142 Customers"
        data-monster-option-values-change="+21.4 %"
        data-monster-option-values-direction="30"
        data-monster-option-classes-change="positive"
        data-monster-option-labels-title="New Customers Q1"
        data-monster-option-labels-subtext="Q1 Last Year"
        data-monster-option-values-secondary="117 Customers">
</monster-metric>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Component Design

The monster-metric component is implemented using the Shadow DOM, providing encapsulation of both its internal markup and styles. By leveraging a shadow root, the component ensures that its internal structure remains unaffected by external styles or scripts. This isolation guarantees reliable and consistent rendering across different usage scenarios.

Shadow DOM and Accessibility

Since the component resides within a shadow root, its internal elements cannot be accessed or styled directly from outside. This encapsulation enforces visual and functional consistency and protects the component from accidental interference by global styles. Despite this, the component remains fully accessible, using ARIA attributes and semantic roles to ensure compatibility with assistive technologies.

Customizing Through Exported Parts

Although direct styling of shadow content is restricted, the monster-metric component exposes several exported parts to allow for visual customization. These parts can be targeted using the CSS part selector to apply custom styles without breaking encapsulation or internal logic.

Available Part Attributes

control: Represents the root container of the metric component.
card: Styles the main card wrapper that holds the metric content.
header: Targets the header section, including the icon and title.
metric-value: Represents the main metric value display.
metric-subtext: Styles the subtext and secondary value area.
metric-change: Applies to the area that displays change indicators and arrows.

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


monster-metric::part(card) {
    background-color: #ffffff;
    border: 1px solid #ddd;
    border-radius: 8px;
}

monster-metric::part(metric-value) {
    font-size: 2rem;
    color: #333;
}

Explanation of the Example

monster-metric::part(card): Applies a white background and light border to the metric card.
monster-metric::part(metric-value): Increases the font size and adjusts the color of the main metric value.

Accessibility

Accessibility is a core aspect of the monster-metric component. It supports ARIA attributes such as aria-labelledby and aria-describedby, ensuring that users with screen readers or assistive technologies can interpret its content correctly. The component also includes semantic roles and visually hidden elements to enhance usability for all users, promoting an inclusive web experience.

HTML Structure

<monster-metric></monster-metric>

JavaScript Initialization

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

Exported

Metric

Derived from

CustomElement

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

Option

Type

Default

Description

templates

object

Template definitions

templates.main

string

undefined

Main template

values

object

Value definitions

values.value

number

undefined

The value of the metric

values.change

number

The change of the metric

values.direction

number

270

The direction of the metric

values.secondary

number

The secondary value of the metric

labels

object

Label definitions

labels.title

string

Title of the metric

labels.subtext

string

Subtext of the metric

classes

object

CSS classes

classes.dot

string

monster-theme-primary-1

CSS class for the dot

classes.metricChange

string

undefined

CSS class for the metric change (positive/negative)

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

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

Static methods

[instanceSymbol]()

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

{Metric}

Events

This component does not fire any public events. It may fire events that are inherited from its parent classes.

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