Web components

dev

Overview

When using SDS with ‘closed’ web components (where shadow root is in use), it’s recommended to use the component specific styles to prevent importing the entire SDS (including unneccessary styles) into each component.

Generally you will need to:

Import the standard combined SDS into the root of the page. This allows non web component elements to use SDS, but also provides styling for slot content inside a web component.
Into the web component, import a base file, which includes common styles used by all sds components (such as colors, icons etc). These are required to apply the global styles the outer web component element.
Into the web component, import the component specific styles, used to style the outer web component element.

For ‘open’ web components, importing the standard combined SDS into the root of the page is all that is required, as per normal.

Component specific styles

Component CSS via assets

<!-- Format -->
https://assets.soracom.io/css/sds/<latest|beta|version>/<component>.css

<!-- Example -->
<link rel="stylesheet" href="https://assets.soracom.io/css/sds/beta/notice.css"/>

Component SCSS via npm

<!-- Format -->
@soracom/soracom-design-system/ds/src/components/<component>/build

<!-- Example -->
@import '@soracom/soracom-design-system/ds/src/components/notice/build'

Base styles

Base CSS via assets

<!-- Format -->
https://assets.soracom.io/css/sds/<latest|beta|version>/base.css

<!-- Example -->
<link rel="stylesheet" href="https://assets.soracom.io/css/sds/beta/base.css"/>

Base SCSS via npm

<!-- Format -->
@soracom/soracom-design-system/ds/src/components/base

<!-- Example -->
@import '@soracom/soracom-design-system/ds/src/components/base'

Sample web component

HTML content

<!-- Load the full SDS on the page root -->
<link rel="stylesheet" href="https://assets.soracom.io/css/sds/beta/combined.css" />

<!-- Example simple notice -->
<ds-notice state="info">This is a plain text content inside a closed web component</ds-notice>

<!-- Example notice with html content -->
<ds-notice state="warning">
  <p class="ds-text --label">This is html content inside a closed web component</p>
  <p class="ds-text --small">Morbi leo risus, porta ac consectetur ac, vestibulum at eros. Donec sed odio dui. Nullam quis risus eget urna mollis ornare vel eu leo. Nullam quis risus eget urna mollis ornare vel eu leo. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla vitae elit libero, a pharetra augue. Nullam quis risus eget urna mollis ornare vel eu leo. Aenean lacinia bibendum nulla sed consectetur. Nulla vitae elit libero, a pharetra augue. Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
</ds-notice>

Web component javascript

const dsNoticeTemplate = document.createElement('template');
dsNoticeTemplate.innerHTML = `
<!--
Import the base (minimal global sds css), and component specific (notice) css.

Note: 
This is only required for the outer 'notice component'
HTML content INSIDE this component still uses the combined css loaded
at the root of the page. Because... reasons.
-->
<link rel="stylesheet" href="https://assets.soracom.io/css/sds/beta/base.css"/>
<link rel="stylesheet" href="https://assets.soracom.io/css/sds/beta/notice.css"/>
<div class="ds-notice">
  <slot></slot>
</div>`;

class DsNotice extends HTMLElement {
  constructor() {
    super();
  }

  // List of attributes to use
  static get observedAttributes() {
    return ['state', 'loading'];
  }

  // Check for any attribute changes
  attributeChangedCallback(property, oldValue, newValue) {
    if (oldValue === newValue) return;
    this[property] = newValue;
  }

  // Connect the component and insert
  connectedCallback() {
    // Add the template to the shadowRoot
    const shadowRoot = this.attachShadow({ mode: 'closed' });
    shadowRoot.appendChild(dsNoticeTemplate.content.cloneNode(true));

    // Process attributes

    // Visual states
    if (this.state) {
      shadowRoot.querySelector('div').classList.add('--' + this.state);
    }

    // Loading state
    if (typeof this.loading != 'undefined') {
      shadowRoot.querySelector('div').classList.add('--loading' + this.loading);
    }
  }
}

// Register this component
customElements.define('ds-notice', DsNotice);

Example simple ds-notice webcomponent

XS Mobile 320px Mobile 420px Tablet 680px Desktop 960px