PanelControl API

Constructor, instance methods, properties, and static methods.

Constructor

new PanelControl(elementOrSelector: HTMLElement | string, options?: PanelControlConfig)

Creates a PanelControl bound to one PanelSet. The element is the [data-panelcontrol] container holding the triggers. The PanelSet is discovered from the panels those triggers point at.

Parameters:

elementOrSelector
CSS selector string or HTMLElement of the control container.
options (optional)
Configuration object. See Configuration.
JavaScript 
const control = new PanelControl('#my-tabs');
const control = new PanelControl(document.querySelector('[role="tablist"]'), { activation: 'auto' });

Instance methods

panelControl.show(panelId: string, options?): void

Activates a tab’s panel through the linked PanelSet (the same thing a trigger click does). Does nothing if there is no linked PanelSet.

Parameters:

panelId
ID of the panel to activate (a trigger’s aria-controls target).
options (optional)
Same ShowOptions as PanelSet.show(): event, transition, autoFocus.
JavaScript 
control.show('panel-2');

panelControl.setTabState(panelId: string, state: 'enabled' | 'disabled'): void

Locks or unlocks the tab(s) controlling a panel. PanelControl only applies the state. It does not decide when a tab should be locked (that is the caller’s concern, e.g. your application code).

Parameters:

panelId
aria-controls target id of the tab(s) to update.
state
'disabled' sets aria-disabled (keyboard nav skips the tab, clicks / Enter no longer activate it, and it cannot hold the roving tab stop). 'enabled' clears it.
JavaScript 
control.setTabState('step-3', 'disabled');   // lock
control.setTabState('step-3', 'enabled');    // unlock

panelControl.destroy(): void

Removes all listeners and drops the element.panelControl reference. The DOM is left as-is.

Instance properties

panelControl.element: HTMLElement

Read-only. The [data-panelcontrol] container element.

panelControl.panelSetElement: HTMLElement | null

Read-only. The PanelSet container this control drives, or null if none can be found. Resolved lazily on first access and cached. An explicit data-panelcontrol="#selector" wins, otherwise it is discovered from the triggers. Because it is lazy, a PanelSet added after init resolves on first use.

panelControl.panelSet: PanelSet | undefined

Read-only getter. The live PanelSet instance, resolved lazily from panelSetElement. undefined until that PanelSet has initialised.

panelControl.config: PanelControlConfig

Read-only. The merged configuration (1. defaults 2. constructor options 3. data attributes).

Static methods

PanelControl.init(selectorOrOptions?, options?): PanelControl[]

Initialises all controls matching the selector. Stores the instance on each container as container.panelControl.

Parameters:

selectorOrOptions (optional)
CSS selector string, or a config object (uses the '[data-panelcontrol'] selector).
options (optional)
Config object, only used when the first argument is a selector string.

Returns:

Array of created PanelControl instances.

JavaScript 
PanelControl.init();
PanelControl.init({ activation: 'auto' });

PanelControl.defaults: PanelControlConfig

Static property. Default configuration applied to all new instances. Modify to change defaults globally.

Web component

registerPanelControl(prefix?: string): void

Defines the <ps-panelcontrol> custom element. Pass a prefix to change the name (default ps). Safe to call multiple times.

JavaScript 
import { registerPanelControl } from 'panelset';
registerPanelControl();          // <ps-panelcontrol>
registerPanelControl('solar');   // <solar-panelcontrol>

PanelControlElement

The HTMLElement subclass backing <ps-panelcontrol>. Each instance creates a PanelControl in its connectedCallback.

TypeScript types

JavaScript 
import {
	PanelControl,
	type PanelControlConfig,
	registerPanelControl,
	PanelControlElement,
} from 'panelset';

const control = new PanelControl('#my-tabs', { activation: 'auto' });
control.setTabState('step-2', 'disabled');