WidthToggle

A width toggle control that lets users switch between compact and expanded reading or panel widths.

Import

import { WidthToggle } from "@schukai/monster/source/components/layout/width-toggle.mjs";

Source

View source code

Package

@schukai/monster

Since

3.57.0

Width toggle is useful when one content block should switch between compact dashboard mode and reading mode.

Reader mode card

Collapse the text to keep more room for adjacent controls, or expand it when the user should focus on the content itself.

Current width: 40%

Introduction

The Monster WidthToggle lets users switch a reading or panel area between compact and expanded width. Use it when a single content surface should adapt to different reading preferences without navigating away.

When to use WidthToggle

Use it for reader-style layouts: Articles, previews and detail panes often benefit from width control.
Use it when density preferences differ: Some users prefer focus, others prefer more visible context.
Do not use it for arbitrary resizing everywhere: Width changes should have a clear readability benefit.

Typical mistakes

Keep the expanded and compact states predictable. If the layout shifts unrelated areas or breaks content rhythm, the toggle feels like instability instead of user control.

Toggle Width

Use width toggle when the same content should switch between compact and reading-friendly width.

Release notes

Narrow mode keeps the text compact beside other dashboard elements. Wide mode expands the same text area when the reader wants to focus on the content.

Current width: 40%

Javascript

import "@schukai/monster/source/components/layout/width-toggle.mjs";

const widthToggle = document.getElementById("width-toggle-simple-demo");
const log = document.getElementById("width-toggle-simple-log");

widthToggle?.addEventListener("monster-dimension-changed", (event) => {
	log.textContent = `Current width: ${event.detail.dimension}`;
});
import "@schukai/monster/source/components/layout/popper.mjs";

HTML

<section style="display:grid;gap:var(--monster-space-4);container-type:inline-size;">
  <p style="margin:0;">Use width toggle when the same content should switch between compact and reading-friendly width.</p>
  <monster-width-toggle id="width-toggle-simple-demo">
    <div style="display:grid;gap:var(--monster-space-4);padding:var(--monster-space-5);background:var(--monster-bg-color-primary-2);color:var(--monster-color-primary-2);border:1px solid var(--monster-color-border-primary-2);">
      <strong>Release notes</strong>
      <p style="margin:0;">
        Narrow mode keeps the text compact beside other dashboard elements. Wide mode
        expands the same text area when the reader wants to focus on the content.
      </p>
      <p id="width-toggle-simple-log" style="margin:0;">Current width: 40%</p>
    </div>
  </monster-width-toggle>
</section>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Reader Width Toggle

The second example starts in wide mode. This is useful for article-like text or dense review content where reading comfort is the primary concern.

Reader mode

Start wide when long-form content is the primary task, then collapse back to a smaller width once the surrounding interface needs more room again.

Javascript

import "@schukai/monster/source/components/layout/width-toggle.mjs";

HTML

<monster-width-toggle
  data-monster-option-default="wide"
  data-monster-option-width-small="48%"
  data-monster-option-width-wide="92%"
>
  <article
    style="display:grid;gap:var(--monster-space-4);padding:var(--monster-space-5);background:var(--monster-bg-color-secondary-2);color:var(--monster-color-secondary-2);border:1px solid var(--monster-color-border-secondary-2);"
  >
    <strong>Reader mode</strong>
    <p style="margin:0;">
      Start wide when long-form content is the primary task, then collapse back to
      a smaller width once the surrounding interface needs more room again.
    </p>
  </article>
</monster-width-toggle>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Component Design

The Monster WidthToggle component allows dynamic width adjustments of a container or panel. By toggling between predefined states, such as small and wide, users can optimize content visibility and layout space. The component is built using the Shadow DOM for encapsulation, ensuring consistent behavior and styling without external interference.

Shadow DOM and Accessibility

The component uses the Shadow DOM to isolate its internal structure and styling. This approach prevents conflicts with external styles or scripts and ensures that the functionality remains reliable.

Accessibility is ensured with proper keyboard and focus management. The toggle button is interactive and compatible with screen readers for an inclusive user experience.

Customizing Through Exported Parts

The Monster WidthToggle exposes specific exported parts that can be styled using CSS. This allows developers to customize the appearance of the toggle, container, and the content area while preserving the component’s core functionality.

Available Part Attributes

control: Represents the main container for the component.
container: The inner container where width changes are applied.
toggle: The button used to toggle the width between predefined states.
inside: Represents the area where slotted content is displayed.

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


monster-width-toggle::part(container) {
    border: 1px solid #ddd;
    border-radius: 8px;
    overflow: hidden;
    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.2);
}

monster-width-toggle::part(toggle) {
    position: absolute;
    top: 10px;
    right: 10px;
    background-color: #007bff;
    color: white;
    padding: 8px;
    border: none;
    border-radius: 4px;
    cursor: pointer;
    transition: background-color 0.3s ease;
}

monster-width-toggle::part(inside) {
    padding: 16px;
    background-color: #f9f9f9;
    transition: width 0.3s ease;
}

Explanation of the Example

container: Styles the outer container with rounded corners and a subtle box shadow.
toggle: Creates a styled toggle button with padding, a background color, and hover effects.
inside: Adds padding and smooth width transitions to the content area.

Accessibility

Accessibility is ensured through:

Keyboard and focus management for the toggle button.
Compatibility with screen readers.

The toggle button provides visual and interactive feedback to ensure a smooth and inclusive user experience.

HTML Structure

<monster-width-toggle></monster-width-toggle>

JavaScript Initialization

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

Exported

WidthToggle, MODE_SMALL, MODE_WIDE

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

width

string

Dimension

width.initial

string

undefined

Initial dimension of the start panel

width.small

string

40%

Minimum dimension of the start panel

width.wide

string

95%

Maximum dimension of the start panel

default

string

undefined

Default dimension of the start panel

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.

Structural methods

setWidth(mode)

Parameters

mode {string}: mode

Returns

{WidthToggle}

Throws

{Error} no shadow-root is defined

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}

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.