Ontario Design System React Component Library

• Introduction
• Installation and usage
• Support

Introduction

This library was generated using Stencil's React output target dependency. It is based on the Ontario Design System Component Library built using Stencil. For more information, find it on NPM.

React 19 support and tooling

This package targets React 19 and ships bindings that align with React 19's JSX/runtime expectations and tooling. React 18 is no longer supported by this package's peer dependencies.

Next.js App Router guide

For Next.js-specific setup guidance, including SSR configuration and asset handling, use the official Next.js integration guide.

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 React component library, follow these steps:

1. Install the npm package.

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

2. Import the theme file into your project’s entry point.

   import '@ongov/ontario-design-system-component-library-react/styles';

3. Configure the asset path (recommended when assets are not served from /).

   import { setAssetPath } from '@ongov/ontario-design-system-component-library-react';
   
   setAssetPath(`${window.location.origin}/assets/`);

   Call setAssetPath once, before rendering any components. This ensures Stencil can resolve component assets (fonts, images, favicons) when they are hosted under a custom base path.

   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.

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

4. Import the desired components from the component library.

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

Usage

You can now use the React components in your component and template files.

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

<OntarioBlockquote
	attribution="Survey respondent"
	quote="Access to high-quality child care is an issue that impacts our entire society."
></OntarioBlockquote>

Next.js

For Next.js App Router projects, follow the dedicated Next.js integration guide. Use the same Sass-based styles entry described above, and follow the guide for SSR-specific configuration and asset handling.

Sass (optional)

If you use Sass and want pkg: resolution via @use, import the styles entry point:

@use 'pkg:@ongov/ontario-design-system-component-library-react/styles' as ods;

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

Support

Contact us at [email protected] for assistance with this package or via opening a GitHub issue.