slim.js Documentation

slim.js is a declarative web components library built on modern web standards. Key characteristics include:

• Reactivity: It uses Handlebars-style syntax to create bindings. It efficiently updates the DOM only when relevant properties change.
• Lightweight Core: The core is less than 3kB gzipped. It scans HTML for Handlebars syntax and executes it within the component's scope.
• Extensibility: You can add custom directives to the registry or create global plugins that hook into the component lifecycle.
• Standard-Compliant: Built on custom-elements technology, making components reusable across different environments without interference from other frameworks.

Slim templates use Handlebars-style syntax ({{...}}) to bind data to the DOM.

When you use {{this.propertyName}} within a template, slim.js automatically wraps that property with a getter and setter. When the property value changes on the component instance, slim.js detects the change and automatically updates the corresponding text node or attribute in the DOM.

Note that some directives can execute code without requiring Handlebars syntax and do not require property change detection.

slim.js components use a template static property containing HTML with handlebars-like syntax (e.g., {{this.propertyName}}) to declare reactive data bindings.

Key Reactivity Rules:

• Prefixing: All component properties must be accessed using the this.* prefix inside templates.
• Immutability: slim.js assumes data structures are immutable to avoid expensive dirty-checking. If you mutate an object internally, the DOM will not update. To trigger an update after mutation, you must re-set the property to itself (e.g., this.userInfo = this.userInfo) or use Utils.forceUpdate.
• Style Binding: You can bind data directly into <style> nodes to reactively update CSS values.

<header>
  <span class="user-info">
    <img class="avatar" src="{{this.userInfo.profileImage}}" />
    {{this.userInfo.username}}
  </span>
</header>

You can access child elements using standard DOM methods like this.querySelector() or this.shadowRoot.querySelector().

Important Lifecycle Constraint: You cannot use these native methods to access children before the onRender() callback has completed, as the elements will not yet be present in the DOM.

To create a reactive Web Component, extend the Slim class and use decorators for defining the custom element tag and its HTML template. Slim uses a declarative syntax where code wrapped in double curly braces {{ ... }} is executed reactively. When properties used in the template change, only the specific bound DOM nodes are updated.

import { Slim } from 'slim-js';
import { tag, template } from 'slim-js/decorators';

@tag('my-awesome-element')
@template(`
<button @click="this.inc()"> + </button>
<span>{{this.count}}</span>
<button @click="this.dec()"> - </button>
`)
class extends Slim {
  count = 0;
  inc() { this.count++ }
  dec() { this.count-- }
}

You can install the slim-js package using your preferred package manager.

npm install slim-js
# or
yarn add slim-js

By default, slim.js components use Shadow DOM to encapsulate styles and render content. If you need to render content in the Light DOM (for example, to allow global CSS to affect component internals or for easier integration with certain legacy tools), you can opt-out of Shadow DOM using one of three methods: a static getter, a static property, or the @useShadow decorator.

// Method 1: Static getter
class MyTag extends Slim {
  static get useShadow() {
    return false
  }
}

// Method 2: Static property
class MyOtherTag extends Slim {}
MyOtherTag.useShadow = false;

// Method 3: Decorator
import {useShadow} from 'slim-js/decorators';

@useShadow(false)
class MyDecoratedTag extends Slim {}

If you prefer not to use a package manager, you can load slim.js directly from a CDN using either an IIFE (global) or a Module script.

<!-- IIFE / Global -->
<script src="https://unpkg.com/slim-js"></script>

<!-- Module -->
<script src="https://unpkg.com/slim-js?module"></script>