Skip to main content

Ontario Design System Component Library

Built With Stencil

Introduction​

Web Components are a set of web platform APIs that enable the creation of custom, reusable, encapsulated HTML tags to use in web pages and web apps. They allow for all logic, styles and component-specific layout to be handled in one place.

They are used in a similar way to other HTML elements, like <input> or <button>, that form the building blocks of the web.

The Ontario Design System component library package contains all the available Ontario Design System components and can be used anywhere that HTML and JavaScript are available.

The package also makes use of the Ontario Design System global styles package for global styles and assets necessary for the Ontario Design System look and feel.

For more information on this package, find it on NPM.

Framework specific packages​

Use this package if you are working with plain HTML or any framework/tooling that does not use a SPA framework. To use the Ontario Design System Web components for either Angular or React, please review instructions in the respective packages:

Installation and usage​

There are two ways to install the Ontario Design System component library package into your project: through NPM or through a CDN.

Installing the NPM package​

  1. Install the NPM package.

    npm install --save @ongov/ontario-design-system-component-library

  2. Add the following script tags to your HTML to import the component library, adjusting the paths to fit your setup.

    <link
        rel="stylesheet"
        href="node_modules/@ongov/ontario-design-system-global-styles/dist/styles/css/compiled/ontario-theme.css"
    />
    <script
        type="module"
        src="node_modules/@ongov/ontario-design-system-component-library/dist/ontario-design-system-components/ontario-design-system-components.esm.js"
    ></script>
    <script
        nomodule
        src="node_modules/@ongov/ontario-design-system-component-library/dist/ontario-design-system-components/ontario-design-system-components.js"
    ></script>

CDN​

A quick and easy way to get started with the Web Components without having to use a package is to use the published CDN version. The CDN used in this example is Unpkg, but other CDNs should work.

Note: The version number should be updated to match the version of the Web Components you want to use, for example, the version used here is 2.7.0.

<link
    rel="stylesheet"
    href="https://unpkg.com/@ongov/ontario-design-system-global-styles@2.7.0/dist/styles/css/compiled/ontario-theme.css"
/>
<script
    type="module"
    src="https://unpkg.com/@ongov/ontario-design-system-component-library@2.7.0/dist/ontario-design-system-components/ontario-design-system-components.esm.js"
></script>
<script
    nomodule
    src="https://unpkg.com/@ongov/ontario-design-system-component-library@2.7.0/dist/ontario-design-system-components/ontario-design-system-components.js"
></script>

Usage​

After installing the necessary styles and web components package, components can then be used as HTML elements within your site.

<ontario-button type="primary">Click me!</ontario-button>
<ontario-radio-buttons
    name="radios"
    hint-text="Hint text for the radio button group."
    caption='{
      "captionText": "Radio legend",
      "captionType": "heading"
   }'
    required="false"
    options='[
      {
         "value": "radio-option-1",
         "elementId": "radio-1",
         "label": "Radio option 1 label"
      },
      {
         "value": "radio-option-2",
         "elementId": "radio-2",
         "label": "Radio option 2 label",
         "hintExpander": {
            "hint": "Hint expander for radio option 2",
            "content": "Example hint expander content for radio option 2."
         }
      },
      {
         "value": "radio-option-3",
         "elementId": "radio-3",
         "label": "Radio option 3 label"
      },
      {
         "value": "radio-option-4",
         "elementId": "radio-4",
         "label": "Radio option 4 label"
      }
   ]'
    hint-expander='{
      "hint": "Hint expander for the radio button group",
      "content": "Example hint expander content for the radio button group."
   }'
>
</ontario-radio-buttons>

Component documentation​

For more information about using the Ontario Design System component library package web components, see Using the components in the Ontario Design System Guidance.

Getting started for Design System developers​

To run the components in development mode, run:

npm start

To build the component for production, run:

npm run build

To run the unit tests for the components, run:

npm run test

Support​

Contact us at design.system@ontario.ca for assistance with this package.

References​

Stencil is a compiler for building fast web apps using Web Components.

Stencil combines the best concepts of the most popular frontend frameworks into a compile-time rather than run-time tool. Stencil takes TypeScript, JSX, a tiny virtual DOM layer, efficient one-way data binding, an asynchronous rendering pipeline (similar to React Fiber), and lazy-loading out of the box, and generates 100% standards-based Web Components that run in any browser supporting the Custom Elements v1 spec.

Stencil components are just Web Components, so they work in any major framework or with no framework at all.