import { OntarioButton} from '@ongov/ontario-design-system-component-library-react'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # ontario-button Use buttons to help the user carry out an important action such as starting a transaction or agreeing to a purchase. ## Usage guidance Please refer to the [Ontario Design System](https://designsystem.ontario.ca/components/detail/buttons.html) for current documentation guidance. ### Disabled state This component intentionally does not provide a `disabled` prop. Disabling action controls can create accessibility and usability barriers, and often does not explain what the user needs to fix. Instead: - keep actions available - use validation and error messaging to clearly identify missing or invalid input When used in forms, pair button behavior with component-level error handling guidance in related form fields. Source: https://designsystem.ontario.ca/components/detail/buttons.html#disabled-buttons ## Configuration Once the component package has been installed (see Ontario Design System Component Library for installation instructions), the button component can be added directly into the project's code, and can be customized by updating the properties outlined [here](#properties). Please see the [examples](#examples) below for how to configure the component. ## Examples Example of a bare-bones button component where the `label` for the button is provided. The default button type will be `secondary`, and the native HTML button type will be `button`. ```mdx-code-block ``` ```html Element Content ``` ```mdx-code-block ``` ```tsx Element Content ``` ```mdx-code-block ``` ```html Element Content ``` ```mdx-code-block ``` Element Content Example of a button component, which includes the `label`, `elementId`, `htmlType`, `type` and `ariaLabelText` properties. ```mdx-code-block ``` ```html Element Content ``` ```mdx-code-block ``` ```tsx Element Content ``` ```mdx-code-block ``` ```html Element Content ``` ```mdx-code-block ``` Element Content Example of a button component rendering as a native link when `href` is provided. Use this pattern for navigation, and keep `htmlType` for action and form-submit use cases. ```mdx-code-block ``` ```html Browse services ``` ```mdx-code-block ``` ```tsx Browse services ``` ```mdx-code-block ``` ```html Browse services ``` ```mdx-code-block ``` Browse services This is another example of a button component, where the user is passing in the label through the `label` property - overriding the 'Element Content' value. The resulting label text will display as `Example`. ```mdx-code-block ``` ```html Element Content ``` ```mdx-code-block ``` ```tsx Element Content ``` ```mdx-code-block ``` ```html Element Content ``` ```mdx-code-block ``` Element Content An example of how to pass in an `onclick` function to the button component. ```mdx-code-block ``` ```html Element Content ``` ```mdx-code-block ``` ```tsx Element Content ``` ```mdx-code-block ``` ```html Element Content ``` ```mdx-code-block ``` ### Forms The `ontario-button` supports integration with native HTML `
` elements. This element integrates with the underlying browser form API and should work the same as adding an ``. To use the `ontario-button` as a submit button set the `htmlType` to `"submit"`. This will wire the `ontario-button` up to the `` it is in and allow it to perform the submit. Internally, the `ontario-button` will fire a `submit` event on its parent `` and trigger the native behaviour of the browser. When `href` is provided, the component renders as a native link instead. In that mode, `htmlType` is ignored and should not be used for form submission. ```html Submit
``` Alternatively, adding a `click` listener with a custom handler will allow for any action to be performed with the `ontario-button`. To trigger the submit the `
` element can programmatically have the `submit` event dispatched to it. ```html Submit
``` ## Accessibility It is important to know when the proper use-case is for a button. Often, the roles of links and buttons can get confused with one another. - Links will redirect you to a new page or another section/component on a page. - Buttons will trigger an action, such as opening or closing a modal, or submitting a form. It can be confusing and frustrating for users to expect a button to trigger an action, and then they are redirected to a new page. ## Technical Note: SSR (Server-Side Rendering) Considerations The Ontario Button component supports server-side rendering, with a few considerations: - **Preferred content source:** Pass button text through the `label` prop. - **Slotted content caveat:** Slotted children rely on fallback `host.textContent`, which is not reliably available during SSR. - **Framework guidance:** For deterministic SSR output, prefer `label` over slotted children. ### SSR-safe example: ```html ``` ## Overview Ontario Button triggers actions and supports button or link behavior. This component intentionally does not expose a `disabled` prop. To support accessible and understandable form completion: - keep actions available - use validation and error messaging to guide corrections instead of disabling For component guidance, see: - https://designsystem.ontario.ca/components/detail/buttons.html - https://designsystem.ontario.ca/developer-docs/components/ontario-button/ Disabled/read-only policy source: - https://designsystem.ontario.ca/components/detail/buttons.html#disabled-buttons ## Properties | Property | Attribute | Description | Type | Default | | --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | ------------- | | `ariaLabelText` | `aria-label-text` | Provides more context as to what the button interaction is doing. This should only be used for accessibility purposes, if the button interaction requires more description than what the text provides. This is optional. | `string \| undefined` | `undefined` | | `elementId` | `element-id` | The unique identifier of the button. This is optional - if no ID is passed, one will be generated. | `string \| undefined` | `undefined` | | `href` | `href` | When provided, the component renders as a native anchor for navigation use cases. This takes precedence over `htmlType`, so form-submission behaviour is disabled in link mode. | `string \| undefined` | `undefined` | | `htmlType` | `html-type` | The native HTML button type the button should use. If no `htmlType` is passed, it will default to `'button'`. This prop only affects the component when it renders as a native `