Government of Ontario
Français

Ontario Design System

Web components

Learn how to use the web component library within your website or application.

Before you get started

Visit the For developers page to learn about options for working with the Design System code and to get a link to the code distribution package.

On this page

About web components

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.

We offer the web components as a library. They come in two packages:

  • the primary component library package for use with HTML or any framework
  • a specific package for use in React applications

We plan to support other JavaScript frameworks in the future.

Packages

The Ontario Design System web components are developed using a toolchain called Stencil and are available via NPM (Node Package Manager) packages.

The use of NPM allows our team to create, update and release components that are versioned and consistent across all uses of the web component library.

Choosing the right package for your project

The Ontario Design System offers 4 packages that bundle different parts of the Design System offering:

Most developers will want to choose the Component Library or Component Library - React packages, depending on your needs. For example, if you are using React, use the Component Library - React package.

Design tokens

The design tokens package includes all of the design tokens that are raw values used throughout the design system, such as colours, fonts, and generic elements and layouts.

It forms the base of the Ontario Design System NPM packages, and can also be used to access the design tokens directly in projects where you don’t want to use the Global Styles package.

Global styles

The global styles package is required to use the Ontario Design System components.

It includes the Ontario Design System global styles that are used for more generic elements and layouts, as well as font assets.

Component Library

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

It also contains assets that can be copied for use with your project, such as logos and more.

Use this package if you are working with plain HTML or any framework/tooling that does not use React.

Component Library - React

The React component library contains the same components as the component library, except they are wrapped for use within React natively.

It also contains assets that can be copied for use with your project, such as logos and more.

Use this package if you are working with React for your application, including with toolchains like Gatsby or NextJS.

Getting started

First, review Choosing the right package for your project to make sure you know what packages you want to use.

Component Library

Follow these steps to import the Component Library into your project:

  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.

    <script type="module" src="dist/ontario-design-system-components/ontario-design-system-components.esm.js"></script>
<script nomodule src="dist/ontario-design-system-components/ontario-design-system-components.js"></script>

  3. Components can then be used as HTML elements within your site.

    <ontario-button type="primary">Click me!</ontario-button>

Component Library - React

Follow these steps to import the Component Library - React into a React project:

  1. Install the NPM package.

    npm install --save @ontario-digital-service/ontario-design-system-component-library-react

  2. Import the desired components from the component library.

    import { OntarioButton } from '@ontario-digital-service/ontario-design-system-component-library-react';

  3. Components can then be used as regular React components.

    <OntarioButton type="primary">Click me!</OntarioButton>

Local assets

Along with the components, the local assets (logos, fonts, etc.) need to be copied into your project so that they are available for bundling upon building your React application.

The assets in the NPM package are located at @ontario-digital-service/ontario-design-system-component-library-react/dist/assets, and should be copied to your public assets folder.

In a standard React application this can be done in a number of ways. One way is to use the copyfiles NPM package, which you can with any operating system:

copyfiles -E -f "node_modules/@ontario-digital-service/ontario-design-system-component-library-react/dist/assets/*" public/assets

Pro tip: If using a package.json file, add a script to make keeping the assets up-to-date simpler.

Using the components

Each component is a rich JavaScript object. They act and behave as regular HTML elements, but are capable of defining their own behaviours and layouts.

When rendered, the components use a Shadow DOM to maintain their encapsulation, handling their own styles and code.

The environment the components are used in will determine the appropriate syntax. However, they are generally used like regular HTML elements or React components, with data passed to each component via attributes/properties, respectively.

Component Documentation

Download the component developer documentation (zip file) for guidance on working with each component.

Attributes and properties

Component properties allow for data to be passed to the component to change the state of the component, configure styles and more.

Using attributes in HTML

Properties can be passed to each component as strings via HTML attributes when using the components directly in HTML.

Properties that take in objects rather than just plain strings can do so using a JSON string:

<ontario-input name="postal" input-width="7-char-width" caption='{"captionText": "Postal Code", "captionType": "default"}' hint-text="For example, A1A 1A1"></ontario-input>

Using properties in HTML with JavaScript

The components can also be interacted with via JavaScript within the browser.

You can query the element and manipulate its properties using regular JavaScript within <script> tags.

<ontario-input></ontario-input>
<script>
    const ontarioInputElement = document.querySelector('ontario-input');
    ontarioInputElement.name = 'postal';
    ontarioInputElement.inputWidth = '7-char-width';
    ontarioInputElement.caption = { captionText: 'Postal Code', captionType: 'default' };
    ontarioInputElement.hintText = 'For example, A1A 1A1';
</script>

Using properties in React

React, unlike HTML, has the benefit of a full JavaScript environment. This makes working with the components even easier.

The React version of the components behave like native React components.

When used within a supported editor, TypeScript typing information is available to help you work with the components.

Properties use JavaScript types as appropriate, which include strings, numbers and objects.

<OntarioButton type="primary">Click Me!</OntarioButton>

Styling

The web components are impacted by two types of styles: internal styles and external styles.

Internally, the components come with their own built-in styles that are contained within their Shadow DOM. These styles are handled separately from any external styles and cannot be interacted with directly. This feature allows us to keep the components consistent with the Design System standards while delivering high quality, tested components.

Externally, the components can be styled and integrated into your application by styling them with external styles, the same as any other web element.

<style>
    .footer {
        margin-top: auto;
    }
</style>

<ontario-footer class="footer" …></ontario-footer>

Release updates

Our components are released via NPM, and are versioned using semantic versioning. This makes it easy for those using the components to keep track of what version of the components their project is using.

To update the components when a new version is released, run:

Component Library

npm update @ontario-digital-service/ontario-design-system-component-library

Component Library - React

npm update @ontario-digital-service/ontario-design-system-component-library-react

Learn more

Check out these resources to learn more about web components:

Contact us

If you have any questions or feedback, please get in touch.