Ontario Design System Component Library

Package moved to @ongov namespace

This npm package has moved to a new namespace, the @ontario-digital-service/ontario-design-system-component-library has moved to @ongov/ontario-design-system-component-library. Package names are not changing - just the namespace.

Please make sure to update your projects to the new versions of the packages under @ongov so you will continue to receive updates. Packages under @ontario-digital-service will no longer be updated.

• Introduction
• Installation and usage
• Component documentation
• Getting started for Design System developers
• Support
• References

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:

• Ontario Design System Angular component library
• Ontario Design System React component library

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 @ontario-digital-service/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/@ontario-digital-service/ontario-design-system-global-styles/dist/styles/css/compiled/ontario-theme.css"
   />
   <script
   	type="module"
   	src="node_modules/@ontario-digital-service/ontario-design-system-component-library/dist/ontario-design-system-components/ontario-design-system-components.esm.js"
   ></script>
   <script
   	nomodule
   	src="node_modules/@ontario-digital-service/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/@ontario-digital-service/[email protected]/dist/styles/css/compiled/ontario-theme.css"
/>
<script
	type="module"
	src="https://unpkg.com/@ontario-digital-service/[email protected]/dist/ontario-design-system-components/ontario-design-system-components.esm.js"
></script>
<script
	nomodule
	src="https://unpkg.com/@ontario-digital-service/[email protected]/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 [email protected] 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.