kommu Docs 🚧 WIP

# Web Components SDK

Web Components SDK provides a set of custom elements(opens new window) useful for building video chats.

In contrast to TypeScript SDK which enables you more finer control, Web Components SDK are suitable when you want to prototype rapidly a feature that involves video chats, to rely on the best practices.

# Web Components Basics

You don't need to master custom elements(opens new window) to use Web Components SDK, but there's a few concepts you'd like to be familiar with (I linked some of excellent articles on MDN just for reference, don't have to read through):

  • Shadow DOM(opens new window) : DOM tree inside custom elements are seperated from the regular DOM tree of document the custom element is attached to, in various way. For instance, result of getElementsByTagName('span') won't include the span elements inside custom elements. Also, styles defined in parent document doesn't take an effect to the one inside custom elements.
  • CSS Shadow Parts and ::part() presude-element(opens new window) : As said above, you cannot apply stylesheets to elements inside custom elements. To make it customizable, some elements inside custom elements have part attributes, which allows you to apply stylesheets via ::part() pseudo-elements. For example, <kommu-video> have a part called speaker-screen. You can apply stylesheet using kommu-videochat::part(speaker-screen). They behave like class attribute in regular DOM.
  • Slots(opens new window) : Some custom elements have slots which allows you to inject a piece of HTML into specific part of the element. You can leverage this to customize the look-and-feel or to expand functionality of the element.
  • Events: Elements sometimes emit an event to notify you that something has happened. For example, <kommu-signin> emits signedin event when user has signed in and LoginUser instance are available. You can listen this by calling addEventListener('signedin', handler) just like for regular elements and events.
  • Methods on custom elements: Some elements expose methods useful for building features around video chat.

# Setup

You can start using Kommu Web Components SDK just by loading the bundles and put, for example, <kommu-starter> element. api-key attribute is only required attributes, which must be your API key displayed on your Kommu Dashboard.

This is an example you can use as a good start point. You can see it running live on try.kommu.app(opens new window) .

<kommu-starter
  api-key="kommu_pk_...="
  room-name="meet-on-kommu-lp">
</kommu-starter>

<script src="https://js.kommu.app/sdk/latest/kommu-webcomponents.js"></script>
<script src="https://js.kommu.app/sdk/latest/kommu.js"></script>

# Calling methods

Once you get object of Kommu elements, you can call methods on the object:

const videoChat = document.getElementsByTagName('kommu-videochat')[0]; // Of course you must have just one <kommu-videochat> in your page
videoChat.startVideoChat();

# Using events

You can listen to event emitted by kommu elements:

const signIn = document.getElementsByTagName('kommu-signin')[0];
signIn.addEventListener('signedin', (event) => {
  console.log('User has signed in!', event.detail.currentUser);
});

# Customize look-and-feel

You can apply stylesheets with ::part() pseudo-elements:

kommu-signin::part(button) {
  background: red;
  padding: 0.1em 0.3;
}
kommu-signin::part(input) {
  background: blue;
  padding: 0.1em 0.3;
}

<kommu-signin api-key="kommu_pk...="></kommu-signin>

# Common Problems

# DOM APIs cannot get kommu elements

Maybe because your script runs before kommu elements defined. You can wait until it using customElements.whenDefined:

customElements.whenDefined('kommu-chat').then(() => {
  const e = document.getElementsByTagName('kommu-chat');
  console.log('kommu-chat is available from now on!', e);
});

← Starter Component →