Web Components

Learn more about the different aspects of Web Components.

Overview

The OLYSENSE Design System (ODS) provides a collection of reusable Web Components to build User Interfaces. Web Components are HTML Custom Elements and are tech stack agnostic. You can use them like any other HTML element.

If you’re new to Web Components, this section will familiarize you with the different aspects of Web Components.

Attributes and Properties

Attribute

A piece of information defined directly within the HTML tag to provide initial values for an element. 

<input type="text" value="initial value" />

Property

Properties are part of the DOM and represent the current state of an element. They are dynamic and can change as the user interacts with the page or through JavaScript. 

const inputElement = document.querySelector('input');
console.log(inputElement.value); // Logs the current value of the input element
inputElement.value = 'new value'; // Changes the current value of the input element

Events

You can listen for standard events such as click, mouseover, etc. as you normally would. However, it’s important to note that many events emitted within a web component’s shadow root will be retargeted to the host element. This may result in multiple click handlers executing even if the user clicks just once. Furthermore, event.target will point to the host element, possibly making things even more confusing.

As a result, you should almost always listen for custom events instead. For example, instead of listening to click to determine when an <ods-checkbox> gets toggled, listen to sense-change. 

<ods-checkbox>Check me</ods-checkbox>


<script>
  const checkbox = document.querySelector('ods-checkbox');
  checkbox.addEventListener('ods-change', event => {
    console.log(event.target.checked ? 'checked' : 'not checked');
  });
</script>

All custom events are prefixed with sense- to prevent collisions with standard events and other libraries. Refer to a component’s documentation for a complete list of its custom events.


Methods

Some components have methods you can call to trigger various behaviors. For example, you can set focus on a <ods-input> using the focus() method. 

<ods-input></ods-input>


<script>
  const input = document.querySelector('sense-input');
  input.focus();
</script>

Refer to a component’s documentation for a complete list of its methods and their arguments.


Slots

Many components use Slots to place content inside of them in specific places. The most common slot is the default slot, which includes any content inside the component that doesn’t have a slot attribute.

For example, a Button’s default slot is used to populate its label. 

<ods-button>Click me</ods-button>

Some components also have named slots. A named slot can be populated by adding a child element with the appropriate slot attribute. Notice how the icon below has the slot=“prefix” attribute? This tells the component to place the icon into its prefix slot. 

<ods-button>
  <ods-icon slot="prefix" name="trash"></ods-icon>
  Delete
</ods-button>

The location of a named slot doesn’t matter. You can put it anywhere inside the component and the browser will move it to the right place automatically!

Refer to a component’s documentation for a complete list of available slots.

Self-closing Tags

Web Components cannot have self-closing tags. Similar to <script> and <textarea> , you must always include the full closing tag. 

<!-- Don't do this -->
<ods-button />


<!-- Always do this -->
<ods-button>Click me!</ods-button>

Usage

Set Initial Value With Attribute

Many Web Components have properties that can be set using attributes. For example, Buttons accept a size attribute that maps to the size property which dictates the button’s size. 

<ods-button size="small">Click me</ods-button>

Some properties are boolean, so they only have true/false values. To activate a boolean property, add the corresponding attribute without a value. 

<ods-button disabled>Click me</ods-button>

Pass Data With Property

In rare cases, a property may require an array, an object, or a function. For example, lets say we have a custom color picker that can list preset swatches. To customize the color picker’s list of preset swatches, you set the swatches property to an array of colors. This must be done with JavaScript if you’re using web components without the React wrapper. 

<ods-application-user-menu id="user-menu"></ods-application-user-menu>


<script>
  const menu = document.querySelector(`#user-menu`);
  menu.languages = [
    {
      label: 'English',
      description: 'English'
    },
    {
      label: 'Deutsch',
      description: 'Germany'
    }
  ];
</script>

If you’re using React, you can pass this data directly via a property. 

<OdsApplicationUserMenu
  languages={
    [
      {
        label: 'English',
        description: 'English'
      },
      {
        label: 'Deutsch',
        description: 'Germany'
      }
    ]
  } />

Update State With Property

If you need to change the state of an element, you can use a property to do so. 

const inputElement = document.querySelector('input');
inputElement.value = 'new value';

If you’re using React, you can update it directly via a property. 

const [value, setValue] = useState('');


return (
  <OdsInput value={value} onOdsInput={setValue(value)}></OdsInput>
)

Update State With Property

If you need to change the state of an element, you can use a property to do so. 

const inputElement = document.querySelector('input');
inputElement.value = 'new value';

If you’re using React, you can update it directly via a property. 

const [value, setValue] = useState('');


return (
  <OdsInput value={value} onOdsInput={setValue(value)}></OdsInput>
)

Search