Web components

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

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 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 3 different packages that bundle different parts of the Design System:

• Web Component Library
• Angular Web Component Library
• React Web Component Library

Choose the package that aligns best with your application, depending on your needs. For example, if you are using React, use the React Web Component Library package.

All Ontario Design System packages.

Web Component Library

The web 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 Web Component Library

The Angular web component library package contains the same components as the web 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 Web Component Library

The React web component library package contains the same components as the web 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.

Web Component Library

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

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.

   <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>

"clean:ontario-ds": "rm -rf components/vendor/ontario-ds",
"copy:ontario-ds": "npm run clean:vendor && copyfiles -u 3 \"node_modules/@ongov/ontario-design-system-component-library/dist/**\" components/vendor/ontario-ds"

Angular Web Component Library

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

1. Install the npm package.

   npm install --save @ongov/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 '@ongov/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 Web Component Library

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

1. Install the npm package.

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

2. Import the desired components from the component library.

   import { OntarioButton } from '@ongov/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 @ongov/ontario-design-system-component-library-react/dist/assets, or @ongov/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:

Angular

copyfiles -E -f "node_modules/@ongov/ontario-design-system-component-library-angular/dist/assets/*" src/assets

React

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

"prebuild": "npm run copy:assets",
"copy:images": "copyfiles -E -f \"node_modules/@ongov/ontario-design-system-component-library-angular/dist/component-library/assets/images/**\" src/assets",
"copy:favicons": "copyfiles -E -f \"node_modules/@ongov/ontario-design-system-component-library-angular/dist/component-library/assets/favicons/**\" src/assets/favicons",
"copy:fonts": "copyfiles -E -u 6 \"node_modules/@ongov/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:

Web Component Library

npm update @ongov/ontario-design-system-component-library

Angular Web Component Library

npm update @ongov/ontario-design-system-component-library-angular

React Web Component Library

npm update @ongov/ontario-design-system-component-library-react

Learn more

Check out these resources to learn more about web components:

• MDN: Web components
• Webcomponents.org: Introduction