The m3e-badge component is a compact visual indicator for counts, presence, or emphasis that can be attached to icons, buttons, or other components.

npm i @m3e/badge

This section outlines usage examples and configuration guidance for the components in this package.

There are three size variants for a badge: small, medium (default), and large. Use the size attribute to control a badge's size.

<m3e-badge size="small">10</m3e-badge>
<m3e-badge size="medium">10</m3e-badge>
<m3e-badge size="large">10</m3e-badge>

An m3e-badge can be anchored to another element using the for attribute, which references the target element’s id. This creates a semantic and visual link, allowing the badge to track its anchor even across layout shifts.

To control placement, use the position attribute. These values define where the badge appears relative to its anchor:

• above-after — Above the anchor, aligned to its end edge (right in LTR, left in RTL)
• above-before — Above the anchor, aligned to its start edge (left in LTR, right in RTL)
• below-before — Below the anchor, aligned to its start edge
• below-after — Below the anchor, aligned to its end edge
• before — Inline with the anchor, placed before it (left in LTR, right in RTL)
• after — Inline with the anchor, placed after it (right in LTR, left in RTL)
• above — Centered above the anchor
• below — Centered below the anchor

These positions are bidi-aware, adapting automatically to left-to-right and right-to-left layouts. They honor expressive anchoring and layout clarity, even across responsive shifts.

<m3e-button id="btn" variant="filled">Button</m3e-button>
<m3e-badge for="btn" position="above-after">AA</m3e-badge>
<m3e-badge for="btn" position="above-before">AB</m3e-badge>
<m3e-badge for="btn" position="below-before">BB</m3e-badge>
<m3e-badge for="btn" position="below-after">BA</m3e-badge>
<m3e-badge for="btn" position="before">BE</m3e-badge>
<m3e-badge for="btn" position="after">AF</m3e-badge>
<m3e-badge for="btn" position="above">A</m3e-badge>
<m3e-badge for="btn" position="below">B</m3e-badge>

By default, badges are not given an ARIA role, indicating that they are treated as neutral, non-semantic elements in the accessibility tree unless explicitly referenced or annotated.

Use aria-describedby when attaching a badge to an interactive element.

This package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/badge/dist/index.js"></script>

In addition, you must use an import map to include additional dependencies.

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js",
      "@m3e/core/bidi": "/node_modules/@m3e/core/dist/bidi.js",
      "@m3e/core/anchoring": "/node_modules/@m3e/core/dist/anchoring.js"

    }
  }
</script>

For production, use index.min.js, bidi.min.js, and anchoring.min.js for faster load times.

This package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.