Ontario Design System Angular Component Library

• Introduction
• Installation and usage
• Debugging FAQs
• Support

Introduction

This library is built using @stencil/angular-output-target and supports Angular versions 20+. It is based off the Ontario Design System Component Library built using Stencil. For more information, find it on NPM.

AI guidance file

This package ships a package-level llms.txt file with AI-oriented integration guidance. Related package guidance is also available in:

• @ongov/ontario-design-system-component-library
• @ongov/ontario-design-system-global-styles

Installation and usage

To find documentation on individual web components in this component library, please download and refer to our component documentation.

To use the Ontario Design System Angular component library, follow these steps:

1. Install the npm package

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

2. Importing the component library styles

There are three supported ways to include the Ontario Design System theme in your Angular application.

Option A: Direct Import in Angular Styles

  Add the following to your global `styles.scss` file:

  ```scss
  @forward 'pkg:@ongov/ontario-design-system-component-library-angular/styles/theme.scss';
  ```

Option B: Create a Separate Styles File

Alternatively, you can create a new SCSS file (e.g., theme.scss). If you need to override the global styles theme with a custom asset base path, you can create a local theme wrapper that forwards the global styles and sets $asset-base-path, then import that wrapper in your app entry point.

@forward 'pkg:@ongov/ontario-design-system-component-library-angular/styles/theme.scss' with (
	$asset-base-path: '/assets'
);

Then, include this file in your Angular project by adding it to the styles array in angular.json:

"styles": [
   "src/theme.scss"
]

Option C: Add the Design System theme CSS

Add the following to the styles array in your project’s angular.json file:

"build": {
"options": {
   "styles": [
      "node_modules/@ongov/ontario-design-system-global-styles/dist/styles/css/compiled/ontario-theme.css"
   ]
}

You may also use the minified version in production if desired: ontario-theme.min.css.

3. Import the ComponentLibraryModule

Import ComponentLibraryModule into your root module. This registers all Ontario Design System web components for use in your Angular application.

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

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

Asset path configuration (optional)

If your app serves component assets (fonts, images, favicons) from a non-root path, configure the asset base path before components render.

import { setAssetPath } from '@ongov/ontario-design-system-component-library-angular';

setAssetPath(`${window.location.origin}/assets/`);

Usage

You can now use the Angular Components in your component template files.

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

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

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

In a standard Angular 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/@ongov/ontario-design-system-component-library-angular/dist/assets/*" src/assets

Another way is to add scripts to copy the assets in your package.json file. For example:

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

Debugging FAQs

You may run into a few errors when first using the Ontario Design System Angular web components library with your Angular project.

Here are a few common ones and how to fix them:

An attribute or property cannot be resolved during compilation (NG8002).

This error arises when attempting to bind to a property that does not exist.

To fix this issue, the CUSTOM_ELEMENTS_SCHEMA must be added to the module schemas for the component. Ex:

import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
	schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

Error: inject() must be called from an injection context (NG0203)

You see this error when you try to use the inject() function outside of the allowed injection context. The injection context is available during the class creation and initialization.

To fix this issue, add mappings to the angular library in the tsconfig.json file. Note that this only applies when using TypeScript path mappings instead of linking to the libraries.

 "compilerOptions": {
     "paths": {
        "@angular/*": ["./node_modules/@angular/*"]
    },
 }

Typescript compiler issues

You may encounter errors building the component library if your compiler options lib is set to a version below ES2022.

If this is the case, you can add the following to your tsconfig.json file:

"complierOptions": {
   "skipLibCheck": true
}

Adding this will skip the type checking of the Angular component library declaration files. This can save time during compilation at the expense of type-system accuracy.

Support

Contact us at [email protected] for assistance with this package.