Ontario Design System React Component Library

• Introduction
• Installation and usage
  • React usage
  • Next.js 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';

   If you need to override the asset base path, create a local theme wrapper:

   // src/styles/ontario-theme.scss
   // Update `$asset-base-path` to match where your app serves Ontario Design System assets.
   @forward 'pkg:@ongov/ontario-design-system-component-library-react/styles/theme.scss' with (
   	$asset-base-path: '/your-assets-path'
   );

   Then import that wrapper in your app entry point.

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}`);

   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. Pass window.location.origin (no /assets/ suffix) — the library's internal asset helper appends the correct path segment automatically.

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

React usage

No additional configuration is required.

Components can be improted directly:

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

When using this package with Next.js App Router, three additional steps are recommended:

1. Configure Next.js for SSR and Sass pkg: support

   Create or update next.config.mjs to include the following:

   import stencilSSR from '@stencil/ssr/next';
   import { pkgImporter } from '@ongov/ontario-design-system-component-library-react/next/sass-pkg-importer';
   
   /** @type {import('next').NextConfig} */
   const nextConfig = {
   	sassOptions: {
   		importer: [pkgImporter],
   	},
   };
   
   export default stencilSSR({
   	module: import('@ongov/ontario-design-system-component-library-react'),
   	from: '@ongov/ontario-design-system-component-library-react',
   	hydrateModule: import('@ongov/ontario-design-system-component-library/hydrate'),
   })(nextConfig);

   Why this configuration is required

   The Ontario Design System Sass uses the pkg: import convention. This allows Sass files to resolve through the package exports field instead of relying on filesystem paths.

   While this works out of the box in other tools, Next.js does not currently resolve pkg: imports automatically.

   The pkgImporter helper adds this support by resolving pkg: specifiers to the correct Sass files in node_modules.

2. Import theme styles

   // src/styles/ontario-theme.scss
   // Update `$asset-base-path` to match where your app serves Ontario Design System assets
   @forward 'pkg:@ongov/ontario-design-system-component-library-react/styles/theme.scss' with (
   	$asset-base-path: '/your-assets-path'
   );

3. Configure asset path (SSR-safe)

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

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