Navigation Back to home

Metric

A beautiful Metric that can make your life easier and also looks good.

Import
the javascript logo
import { Metric } from "@schukai/monster/source/components/data/metric.mjs";
Source
the git logo
Package
the npm logo
Since
4.11.0

Introduction

The monster-metric component is a powerful visual element used to display key data values in a clear and attractive format. Designed to highlight numerical or statistical information, this component is ideal for dashboards, reports, and any interface where data insight is essential. Whether integrated into a simple site or a complex data-driven application, it ensures information is presented clearly and professionally.

Key Features

  • Dynamic value display: Present live or static values with support for direction and change indicators, enabling users to quickly understand key metrics.
  • Customizable layout: Configure templates, styles, and labels directly through HTML attributes or JavaScript, ensuring the component fits your visual and functional needs.
  • Accessible markup: Includes ARIA labels and roles to ensure all users, including those using assistive technologies, can interpret the data effectively.
  • Responsive feedback: Visual indicators such as color-coded changes and directional arrows provide immediate, meaningful feedback for improved data comprehension.
  • Declarative and programmatic configuration: Fully controllable using data-monster-options or JavaScript methods for flexible integration into any application architecture.

Improving the user experience

The monster-metric component enhances user understanding by combining numeric data with directional and contextual cues. Its visual clarity and semantic structure help users make sense of data quickly, reducing cognitive load and supporting better decision-making.

Through carefully designed layout and styling, the component makes data accessible and aesthetically aligned with the overall UI, increasing user satisfaction and interaction efficiency.

Efficiency in the development process

Integration with Monster.js allows for declarative HTML use as well as dynamic JavaScript manipulation, streamlining development workflows. The component’s modularity and compatibility with standard HTML5, CSS, and JavaScript ensure smooth adoption into both new and existing projects. Developers benefit from reduced boilerplate and faster delivery of reliable, professional-grade data components.

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';

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 **/

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
  • {Components.Data.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.