Instance methods

See also

For practical examples of instance methods, see the Components guide and Lifecycle guide.

$log(...content)

Logs content to the console when the instance.$options.log option is set to true, either via the config getter or via the data-options attribute.

Parameters

• ...args (any[]): The content to log

Example

import { Base } from '@studiometa/js-toolkit';

export default class Component extends Base {
  static config = {
    name: 'Component',
    log: true,
  };

  mounted() {
    this.$log('mounted');
  }
}

$warn(...content)

Logs a warning to the console when the instance.$options.log option is set to true, either via the config getter or via the data-options attribute.

Parameters

• ...args (any[]): The content to warn

Example

import { Base } from '@studiometa/js-toolkit';

export default class Component extends Base {
  static config = {
    name: 'Component',
    log: true,
  };

  mounted() {
    this.$warn('Warning!'); // [Component-1] Warning!
  }
}

$on(event, callback[, options])

Bind a callback function to an event emitted by the instance. Returns a function to unbind the callback from the event.

Parameters

• event (string): The name of the event.
• callback (EventListenerOrEventListenerObject): A callback function or an object implementing the EventListener interface.
• options (boolean|AddEventListenerOptions): Options for the addEventListener method, defaults to undefined.

Return value

• () => void: A function to unbind the callback from the event.

Example

import { Base } from '@studiometa/js-toolkit';

export default class Component extends Base {
  static config = {
    name: 'Component',
    log: true,
  };

  mounted() {
    const removeEventListener = this.$on('updated', () => {
      this.$log('updated');
    });

    // Remove the event listener
    removeEventListener();
  }
}

Tip

Set the options.once parameter to run the callback only once.

this.$on('updated', () => {}, { once: true });

$off(event, callback[, options])

Unbind a callback function from an event emitted by the instance. If no callback function is provided, all previously bound callbacks are removed.

Parameters

• event (string): The name of the event.
• callback (EventListenerOrEventListenerObject): The callback function or the object implementing the EventListener interface which was bound to the event.
• options (boolean|AddEventListenerOptions): Options for the removeEventListener method, defaults to undefined.

Example

import { Base } from '@studiometa/js-toolkit';

export default class Component extends Base {
  static config = {
    name: 'Component',
    log: true,
  };

  mounted() {
    const callback = () => this.$log('updated');

    this.$on('updated', callback);

    // Removes the binded callback
    this.$off('updated', callback);
  }
}

$emit(event[, ...args])

Emit an event from the current instance, with optional custom arguments. The instance dispatches the event on its root element, so other components or scripts can listen to it.

Parameters

• event (string | Event): The name of the event or an Event instance.
• ...args (any[]): The data to send with the event.

Example

import { Base } from '@studiometa/js-toolkit';

export default class Component extends Base {
  static config = {
    name: 'Component',
    log: true,
  };

  mounted() {
    this.$on('custom-event', (a, b) => this.$log(a + b)); // 3
    this.$emit('custom-event', 1, 2);
  }
}

$query(query)

Get all descendant component instances matching the given query. This is sugar for queryComponentAll(query, { from: this.$el }).

Parameters

• query (string): a query string in the format ComponentName(.cssSelector):state (see queryComponent)

Return value

• Base[]: an array of all matching descendant instances

Example

import { Base } from '@studiometa/js-toolkit';
import SliderItem from './SliderItem.js';

class Slider extends Base {
  static config = {
    name: 'Slider',
    components: {
      SliderItem,
    },
  };

  mounted() {
    for (const item of this.$query('SliderItem')) {
      this.$log(item.$id);
    }
  }
}

See also

$query is the sanctioned parent → child channel: a parent reads and drives its declared descendants. See Data flow between components.

$closest(query)

Get the closest ancestor component instance matching the given query. This is sugar for closestComponent(query, { from: this.$el }).

Parameters

• query (string): a query string in the format ComponentName(.cssSelector):state (see closestComponent)

Return value

• Base | undefined: the closest matching ancestor instance, or undefined if none found

Example

import { Base } from '@studiometa/js-toolkit';

class SliderItem extends Base {
  static config = {
    name: 'SliderItem',
  };

  mounted() {
    const slider = this.$closest('Slider');
    if (slider) {
      this.$log('Inside slider:', slider.$id);
    }
  }
}

See also

$closest resolves a dynamic ancestor from the DOM and returns Base | undefined. Always guard the result; never dereference it unguarded in mounted(). See Data flow between components.

$mount()

Mount the component and its children. Triggers the mounted lifecycle method.

Return value

• Promise<this>: returns the current instance when all children components are mounted

$update()

Update the children list from the DOM, mount any unmounted components, and re-bind event hooks.

Return value

• Promise<this>: returns the current instance when all children components are updated

TIP

js-toolkit re-mounts already registered or mounted components automatically on newly injected elements. For now, call the $update() method to re-bind event hooks.

$destroy()

Destroy the component and its children. Triggers the destroyed lifecycle method.

Return value

• Promise<this>: returns the current instance when all children components are destroyed

$terminate()

Terminate the component. Its instance becomes available for garbage collection.

Return value

• Promise<void>: returns a promise resolving when all children components are terminated

WARNING

A terminated component can not be re-mounted, use with precaution.

Error handling

Lifecycle methods run their work through a shared task queue, and they are commonly called fire-and-forget ($mount() from the auto-mounting mutation observer, $terminate() when an element leaves the DOM). A rejection there would have no awaiter, so $mount(), $update(), $destroy() and $terminate() resolve even when a lifecycle hook throws.

The error is not swallowed: it is re-thrown from a microtask, so it reaches window.onerror and any error monitor, wrapped in an error naming the instance and the failed lifecycle, with the original error as its cause.

A failed lifecycle stops at the point of failure: after-mounted and after-destroyed are not emitted, and a component whose wiring failed stays unmounted. A component whose mounted() hook threw is wired, so $isMounted is true and $destroy() can still tear it down.

With the blocking feature enabled no queue is involved — the work runs synchronously in the caller's stack — so the lifecycle methods keep rejecting and try { await createApp(App, { blocking: true }) } catch {} still catches startup failures.