Guide: Using demo

Live demo is an interactive playground that renders an instance of a web component and provides UI controls to interact with it. Several panels are available depending on the functionality the component supports.

Importing

In order to use live demo, import the components documented in the manifest. The demo component uses customElements.whenDefined(), which returns a Promise, so importing the components lazily also works.

<script type="module">
  import 'my-element';
</script>
<api-viewer src="./custom-elements.json"></api-viewer>

If you want to render live demo separately from the API documentation, consider using <api-demo> element instead of the <api-viewer>. All of the features and use cases listed below apply to both components.

Source

The Source panel contains an HTML code snippet representing the component with its properties, HTML attributes and slots. When setting knobs or styles using corresponding panels, code snippet is updated.

For example, changing a custom CSS property to the value other than the default one will add <style> tag to the snippet. Toggling knobs removes and sets corresponding HTML attributes on the component, etc.

There is a button to copy the source code snippet content to clipboard. Play with the component to tweak its appearance, set textContent for its <slot> elements, and then try the resulting code in your application!

Knobs

Knobs panel is of the live demo inspired by corresponding Storybook addon. It allows to toggle properties, attributes and set slots content on the element instance, and updates the code snippet accordingly.

The playground listens to the events dispatched by the component and uses [property]-changed events to sync knobs controls with the component's state. This is useful if the component handles user input:

/**
 * A custom element that fires event on value change.
 *
 * @element my-element
 *
 * @prop {string} value - Value of the component
 * @fires {CustomEvent} value-changed - Event fired when value is changed
 */

Styles

The live demo relies on the analyzer to get default values for documented CSS Custom Properties. As a fallback, it collects the values on the rendered component using getComputedStyle(element).getPropertyValue().

We recommend using the following CSS structure to provide styling API for web components to make Styles panel work. Also, this way the <style> tag generated by the code snippet will work properly when copying:

:host {
  --button-color: red;
}

button {
  color: var(--button-color);
}

Events

The Events panel is a convenient way to log the events dispatched by the component, including the serialized event.detail object. Custom events caused by setting knobs are logged, same as user-originated events.

If event.detail is an object that contains a value property, it is always indicated in the log, regardless of the value. The missing value is logged as "undefined", and null and empty string are logged, respectively.