5.0.0-rc.2 · release candidate (published on npm) · f4243b83 snapshot. Reading source: f4243b8334cafe0bd1b06eba85d87e2310cb3618. Match APIs to your installed version.

Region#

API index · View · Shared events

A Region owns the placement and lifetime of one View or CollectionView. Showing another View destroys the current one. Detaching releases it for reuse. A View can own named Regions for composition; an Application can use a Region to display its root View.

Construction and options#

new Region(options?) configures the Region and calls initialize(options). It does not resolve a selector, render a View, or change the DOM. Supply el before showing content. Unlike View, Region has no preinitialize hook.

Functions run with the Region as this. Constructor options take precedence over class defaults. Use common option methods for custom options.

This example moves a live View between two Regions without rendering it again:

import { Region, View, type RegionOptions } from 'marionette';

const options: RegionOptions = { el: document.createElement('section') };
const first = new Region(options);
const second = new Region({ el: document.createElement('aside') });
const content = document.createElement('p');
content.textContent = 'Account settings';
const view = new View({ el: content, template: false });

first.show(view);
const retained = first.detachView();
if (retained) second.show(retained);

first.destroy();
second.destroy(); // Destroys the View now owned by this Region.

See View for named Region definitions, including selector, constructor, instance, and options-object forms.

Showing a View#

show(view, options?)#

Accepts a View or CollectionView instance and returns the Region. It returns undefined when an unmatched selector is allowed by allowMissingEl. Both allowMissingEl and replaceElement can be overridden for this call with boolean values in options.

On a successful show, the Region:

1. Resolves its element and checks the incoming View.
2. Emits before:show, empties the outgoing View, and takes ownership of the incoming View.
3. Renders the incoming View if it is not already rendered.
4. Inserts its element, emitting attach notifications if the Region is in the document and monitoring is enabled.
5. Emits show.

Showing the current View again does not rerender it or repeat show events. A destroyed View cannot be shown. A View already owned by an Application, Region, or CollectionView must first be detached from that owner. A View adopting existing attached markup does not receive another attach notification just because a Region shows it.

An unmatched selector produces MN0005 unless allowed; no configured element produces MN0004. A destroyed incoming View produces MN0007, and an already owned View produces MN0003. allowMissingEl skips that show attempt; it does not establish automatic recovery when a target appears later.

In this prerelease, an unmatched lookup clears the cached el, and subsequent element-dependent operations, including empty(), reset(), and show(), throw MN0004. Resolve the target before creating a Region when it is not yet available.

Operations are synchronous. Lifecycle callbacks that throw interrupt the operation; Region does not roll back partially completed work.

Empty, detach, reset, and destroy#

empty(), reset(), and destroy() use ShowOptions for element checking. The first lookup by empty() without options tolerates an unmatched selector when there is no child; supplying allowMissingEl: false makes that check strict. These options are not passed to the outgoing View's destroy().

Keep a reference to a detached View and either give it a new owner or destroy it when finished. Detachment preserves the View's own listeners and state; its View owner stops forwarding its events. See event cleanup for native destruction and subscription ownership.

Repeated destruction is a no-op. Once destruction begins, show() does nothing and returns the Region; detachView() returns undefined. After destruction completes, empty() and reset() also do nothing and return the Region. Destruction leaves the Region's own element in place, with its owned View removed.

Replacing the Region element#

With replaceElement: true, the Region retains its original placeholder as region.el while the View's element occupies that position in the DOM. Emptying or detaching restores the placeholder. Replacement also works per call with show(view, { replaceElement: true }).

Use a placeholder that has a parent node: replacement exchanges nodes in that parent. isReplaced() reports whether the Region is currently using replacement mode. The placeholder is restored before the outgoing View is destroyed, which changes detach ordering as described below.

Properties and queries#

Lifecycle events and hooks#

Each event uses triggerMethod: its matching hook runs first, then registered event listeners receive the same arguments. See shared events. Hook methods are supplied on a subclass, for example onBeforeShow(region, view, options).

options is the object passed to show() or destroy(), or undefined. Empty events have no options argument. The current View is still present at before:empty and released by empty. Emptying a Region that has no View clears content without emitting empty events. When a child destroys itself, the Region releases it and emits empty events too.

For an occupied Region, destroy() runs: Region before:destroy → Region before:empty → child teardown → Region empty → Region destroy. The last notification observes isDestroyed() === true and cleared View-owner/name references.

Replacing a CollectionView#

Replacement follows the same Region sequence: before:show → before:empty → outgoing child teardown → empty → incoming render/attach → show. The outgoing CollectionView destroys its managed children during its teardown; its before:destroy:children and destroy:children notifications belong to the CollectionView.

Normally the outgoing View receives before:destroy before detach. With replaceElement, restoring the placeholder detaches it before before:destroy. An already rendered incoming View skips rendering. Descendant notifications follow the View lifecycle; monitoring and attachment state determine which detach/attach notifications occur.

Customization and inherited methods#

Use Region.extend(prototypeProperties?, staticProperties?) or subclass Region. initialize(options) is the constructor hook; the default does nothing. For custom constructors and Region.call / Region.apply, see class construction.

These methods are called by lifecycle operations. Calling DOM hooks directly does not perform the ownership bookkeeping of show, empty, or detachView. If overriding a lifecycle method, delegate to Region.prototype to retain the standard cleanup and event contract.

Region.setDomApi(partialApi) merges DOM methods into that class's provider and returns the class. Call it on a Region subclass to scope the override to that subclass. See runtime configuration for setter scope and DomApi for the provider-authoring contract.

Region inherits common utilities: getOption, mergeOptions, normalizeMethods, bindEvents, unbindEvents, bindRequests, and unbindRequests. It also inherits event methods: on, once, off, trigger, triggerMethod, listenTo, listenToOnce, and stopListening. Region has no state, model, collection, renderer, or Radio-channel initialization of its own.

TypeScript types#

All of these types are exported from marionette:

show() is typed as the Region or undefined; detachView() returns SupportedView | undefined. empty(), reset(), and destroy() preserve the derived instance type for chaining. Private lifecycle fields in ViewLifecycle are framework integration details, not fields to mutate in application code.