Ontario.ca homepage
Français

Ontario Design System

Web components

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

Visit the Getting started 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 Angular applications
  • 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.

Complete styles

The complete styles package is a collection of all the Ontario Design System styles.

It includes the Ontario Design System global styles, as well as styles specific to each component. One should use this package if they want to use the styles and assets with the HTML components provided by the Design System, similar to how the distribution package is used.

Component Library

The component library package 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.

Angular Component Library

The Angular component library package contains the same components as the component library. These components are wrapped for use within Angular natively.

The package 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 Angular for your application. Supports Angular 12 and up.

React Component Library

The React component library package 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>

Angular Component Library

Follow these steps to import the Angular Component Library into an Angular project:

  1. Install the NPM package.

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

  2. Import the ComponentLibraryModule, or whichever specific component you want to use into your root module. The ComponentLibraryModule import will include all the Ontario Design System web components.

    import { ComponentLibraryModule } from '@ontario-digital-service/ontario-design-system-component-library-angular/dist/component-library';

@NgModule({
    imports: [ComponentLibraryModule],
})
export class AppModule {}

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

    <ontario-button type="primary">Primary Button</ontario-button>

React Component Library

Follow these steps to import the React Component Library 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 Angular or React application.

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

In a standard Angular or 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:

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

If you’re using a package.json file, add a script to make it simpler to keep the assets up-to-date.

"prebuild": "npm run copy:assets",
"copy:images": "copyfiles -E -f \"node_modules/@ontario-digital-service/ontario-design-system-component-library-angular/dist/component-library/assets/images/**\" src/assets",
"copy:favicons": "copyfiles -E -f \"node_modules/@ontario-digital-service/ontario-design-system-component-library-angular/dist/component-library/assets/favicons/**\" src/assets/favicons",
"copy:fonts": "copyfiles -E -u 6 \"node_modules/@ontario-digital-service/ontario-design-system-component-library-angular/dist/component-library/assets/fonts/**/*\" src/assets/fonts",
"copy:assets": "npm run copy:images && npm run copy:favicons && npm run copy:fonts"

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.

Developer documentation

Visit the Web component developer documentation site to find guidance, examples, and API documentation for the web components and the component library packages, including Angular and React implementations.

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 Angular

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

The Angular version of the components behave like native Angular 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. They can be bound to data following the Angular data binding conventions.

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

Angular Component Library

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

React Component Library

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.