The Component Setup API

computed(fn)

A reference that is always computed on state checks. Takes a function and returns a ref that is auto-updated when scope checks are executed.

ref(val) and shallowRef(val)

ref creates an object with a single property, .value, for which we can track changes.

Changes to any ref value inside a component scope trigger an update.

If the ref contains an object, any property change in that object also triggers an update (deeply checked). An initial value can be given to it.

shallowRef is the mostly the same, with the difference that it will not deeply watch object changes in the ref value.

import { ref, shallowRef } from '@li3/web';

export default function setup() {
  const address = ref({ street: '', number: 0, zipCode: '' });
  const name = shallowRef('');

  return { name, address };
}
Copy

defineEvent(name)

Defines a function that emits a custom event called by name. Use this function to emit a specific event in the template.

import { defineEvent } from '@li3/web';

export default function setup() {
  const onAction = defineEvent('update');
  // ...
  onAction('action');
}
Copy

defineEvents(names)

A convenience method to define multiple events at once. The returned function emits events by name and accepts a second argument:

import { defineEvents } from '@li3/web';

export default function setup() {
  const emit = defineEvents(['one', 'two']);
  // ...
  emit('one', 1);
  emit('two', 2);
}
Copy

defineProp(name, definitions)

Define an input property for a custom element. The component scope is checked every time this property changes.

import { defineProp } from '@li3/web';

export default function setup() {
  const age = defineProp('age', 0);
}
Copy

defineProps(names) / defineProps(table)

Define multiple props in one shot.

import { defineProps } from '@li3/web';

export default function setup() {
  const { left, right } = defineProps(['left', 'right']);
}
Copy

defineQuery(selector)

Return a dynamic object that can either grab a list of child nodes (.many) or one child node (.one)

import { defineQuery } from '@li3/web';

export default function setup() {
  const listItems = defineQuery('li');
  // ...
  listItems.many.forEach((li) => {});
}
Copy

inject(target) and provide(target, value)

An injection mechanism using DOM events. Use provide(target, value) to provide a value to child nodes of a custom element.

In a child node, use inject(target) to retrieve a value from parent nodes. The first parent to provide a value in the DOM tree wins.

<template component="user-avatar">
  <div class="rounded-full w-16 h-16">
    <img bind-src="user?.avatar" class="w-full h-full" />
  </div>

  <script setup>
    import { inject, onInit, shallowRef } from '@li3/web';
    import { $user } from './auth.js';

    export default function setup() {
      const auth = shallowRef(null);
      onInit(() => {
        auth.value = inject($user);
      });
    }
  </script>
</template>

<template app>
  <script setup>
    import { provide, onInit } from '@li3/web';
    import { $user, login } from './auth.js';

    const currentUser = ref(null);
    provide($user, currentUser);

    onInit(async () => {
      currentUser.value = await login();
    });
  </script>
</template>
Copy

loadCss(url)

Loads a CSS stylesheet from url and attaches to the element inside a Shadow Root, if present. Otherwise, adds the stylesheet to document.head and shares it globally.

import { loadCSS } from '@li3/web';

export default function () {
  loadCss('https://example.com/shared-styles.css');
}
Copy

loadScript(url)

Loads a JS file globally on document.head, as a tag. The URL is loaded only once per page.

import { loadScript } from '@li3/web';

export default function () {
  loadScript('https://example.com/shared-library.js');
}
Copy

onInit(fn) / onUpdate(fn) / onDestroy(fn)

Lifecycle hooks for callbacks that run when a component first runs, when any prop changes or when the component is destroyed (in case of custom elements)

import { onInit, onUpdate, onDestroy } from '@li3/web';

export default function () {
  onInit(() => {
    // init component
  });

  onUpdate(() => {
    // an input property has changed
  });

  onDestroy(() => {
    // clean up component state
  });
}
Copy

hostClasses(classes)

Allows to declare CSS classes to be added to the custom element host.

import { hostClasses } from '@li3/web';

export default function () {
  hostClasses('block my-6');
}
Copy