Navigation Back to home

ControlBar

A responsive control bar that groups multiple controls and moves overflowed controls into a menu.

Import
the javascript logo
import { ControlBar } from "@schukai/monster/source/components/form/control-bar.mjs";
Source
the git logo
Package
the npm logo
Since
1.0.0
SavePreviewExportArchive

Introduction

The Monster ControlBar groups controls, keeps them aligned and moves overflowed controls into a popper when space is limited. It is useful for dense application surfaces where buttons, filters and secondary actions need to stay in one command row.

When to use ControlBar

  • Use it for responsive command surfaces: Toolbars, list controls, editor headers and filter rows can keep their primary controls visible while secondary controls move into overflow.
  • Use it with mixed controls: The bar accepts Monster buttons, select controls, native inputs and grouped child elements.
  • Use monster-control-bar-spacer for groups: The spacer is non-interactive and turns into a horizontal separator inside the overflow popper.
  • Do not use it as page layout: It is a control grouping component, not a replacement for panel, board or split layout components.

Responsive layout contract

Layout options can be set as HTML attributes or through setOption(). Use layout.stackedBreakpoint when the bar should change alignment below a measured width and layout.stackedBreakpointContainer when that width should come from a surrounding element.

<monster-control-bar
    data-monster-option-layout-alignment="left"
    data-monster-option-layout-stacked-breakpoint="360px"
    data-monster-option-layout-stacked-alignment="center">
    ...
</monster-control-bar>

Events

The component emits monster-control-bar-layout-changed when its responsive layout state changes. The event detail reports the effective alignment, configured alignment, stacked state and configured breakpoint values.

Typical mistakes

Do not hide overflow actions with page CSS. Let the control move items into the popper. Do not rely on internal slot order; use documented options and events when reacting to layout changes.

Control Bar

This example shows monster-control-bar with grouped actions, a native input and monster-control-bar-spacer. Resize the available width to see controls move into overflow and watch the layout event update the status text.

SavePreviewExportArchive

Width: 420px. Layout changes are reported by monster-control-bar-layout-changed.

Javascript

import "@schukai/monster/source/components/form/button.mjs";
import "@schukai/monster/source/components/form/control-bar.mjs";
import "@schukai/monster/source/components/form/control-bar-spacer.mjs";

await customElements.whenDefined("monster-control-bar");

const widthInput = document.getElementById("control-bar-width");
const frame = document.getElementById("control-bar-frame");
const controlBar = document.getElementById("workflow-control-bar");
const status = document.getElementById("control-bar-status");

let layoutSummary = "waiting for first layout event";

const updateStatus = () => {
  status.textContent =
    "Width: " + widthInput.value + "px. Layout: " + layoutSummary + ".";
};

const updateWidth = () => {
  frame.style.maxWidth = widthInput.value + "px";
  updateStatus();
};

controlBar.addEventListener("monster-control-bar-layout-changed", (event) => {
  const detail = event.detail;
  layoutSummary =
    (detail.stacked ? "stacked" : "inline") +
    ", alignment " +
    detail.alignment;
  updateStatus();
});

widthInput.addEventListener("input", updateWidth);
updateWidth();

HTML

<section class="control-bar-example">
  <label class="control-bar-width-control" for="control-bar-width">
    Available width
    <input id="control-bar-width" type="range" min="260" max="760" step="10" value="420" />
  </label>

  <div id="control-bar-frame" class="control-bar-frame">
    <monster-control-bar
      id="workflow-control-bar"
      data-monster-option-layout-alignment="left"
      data-monster-option-layout-stacked-breakpoint="340px"
      data-monster-option-layout-stacked-alignment="center"
      data-monster-option-layout-stacked-breakpoint-container="#control-bar-frame"
    >
      <monster-button>Save</monster-button>
      <monster-button>Preview</monster-button>
      <monster-control-bar-spacer></monster-control-bar-spacer>
      <input aria-label="Filter records" placeholder="Filter records" />
      <monster-button>Export</monster-button>
      <monster-button>Archive</monster-button>
    </monster-control-bar>
  </div>

  <p id="control-bar-status" class="control-bar-status">
    Width: 420px. Layout changes are reported by monster-control-bar-layout-changed.
  </p>
</section>

Stylesheet

.control-bar-example {
  display: grid;
  gap: var(--monster-space-4);
}

.control-bar-width-control {
  color: var(--monster-color-primary-1);
  display: grid;
  gap: var(--monster-space-2);
}

.control-bar-frame {
  background: var(--monster-bg-color-primary-1);
  border-color: var(--monster-color-border-primary-2);
  border-radius: var(--monster-border-radius);
  border-style: var(--monster-border-style);
  border-width: var(--monster-border-width);
  max-width: 420px;
  padding: var(--monster-space-3);
}

.control-bar-frame input {
  min-width: 10rem;
}

.control-bar-status {
  color: var(--monster-color-primary-1);
  margin: 0;
}
Open in playground

Component Design

ControlBar uses Shadow DOM to measure available space, keep visible controls in the main row and move overflowed controls into a popper slot. Slotted controls remain the source of truth; the component changes placement, not the public control contract.

Public styling surface

Use Monster tokens and exposed parts for styling. Avoid selectors that depend on the internal measurement structure or temporary slot assignment.

Available Part Attributes

  • control: The outer control container.
  • popper-nav: The navigation area that contains the overflow trigger.
  • popper-switch: The button that opens the overflow popper.
  • separator: Exposed by monster-control-bar-spacer.

Useful custom properties

  • --monster-control-bar-height: Shared control height for the bar.
  • --monster-control-bar-select-min-inline-size: Minimum width for slotted select controls.
  • --monster-control-bar-spacer-line-color: Separator color for spacers.
monster-control-bar {
    --monster-control-bar-height: 2.75rem;
}

monster-control-bar::part(popper-switch) {
    border-radius: var(--monster-border-radius);
}

Accessibility

Controls keep their own accessible names and behavior while the bar manages overflow placement. The spacer is decorative and sets aria-hidden="true".

HTML Structure

<monster-control-bar></monster-control-bar>

JavaScript Initialization

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

Exported

ControlBar

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
undefined
Template definitions
templates.main
string
undefined
Main template
object
labels
labels.moreActions
string
More actions
Accessible label for the responsive overflow switch
layout
object
undefined
Responsive layout configuration.
layout.alignment
string
left
Main-row alignment. Supported values are `left`, `right` and `center`.
layout.stackedAlignment
string|undefined
undefined
Alignment used while the configured stacked breakpoint matches.
layout.stackedBreakpoint
string|undefined
undefined
CSS length that switches the bar into stacked layout when the measured width is smaller or equal.
layout.stackedBreakpointContainer
string|undefined
undefined
CSS selector for the element whose width should be used for stacked-breakpoint measurement.
layout.hideWhenEmpty
boolean
false
Hide the control bar when all slotted controls are empty or unavailable.
popper
object
undefined
FloatingUI popper configuration
popper.placement
string
left
Placement of the overflow popper
popper.middleware
array<string>
undefined
Middleware for the popper

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

Behavioral methods

hideDialog()
Returns
  • {ControlBar}
Close the slotted dialog.
showDialog()
Returns
  • {ControlBar}
Open the slotted dialog.
toggleDialog()
Returns
  • {ControlBar}
Toggle the slotted dialog.

Structural methods

setOption(path,value)
Parameters
  • path {string}: path
  • value {*}: value
Returns
  • {ControlBar}
Set option and sync layout state for reactive layout options.

Static methods

[instanceSymbol]()
Returns
  • {symbol}
This method is called by the instanceof operator.
getCSSStyleSheet()
Returns
  • {CSSStyleSheet[]}
This method is called internal and should not be called directly.
getTag()
Returns
  • {string}
This method is called internal and should not be called directly.
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]()
This method is called internal and should not be called directly.
connectedCallback()
Returns
  • {void}
This method is called by the dom and should not be called directly.
disconnectedCallback()
Returns
  • {void}
This method is called by the dom and should not be called directly.

Events

The component emits the following events:

  • monster-control-bar-layout-changed

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.