import { OntarioHintText } from '@ongov/ontario-design-system-component-library-react';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# ontario-hint-text

Use hint text to help users understand how to complete fields in a form. When adding hint text, the first choice should always be to display hint text without using a hint expander.

## Usage guidance

Please refer to the [Ontario Design System](https://designsystem.ontario.ca/components/detail/hint-text.html) for current documentation guidance.

## Configuration

Once the component package has been installed (see Ontario Design System Component Library for installation instructions), the hint text 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 hint text component where the user is passing the `hint` directly as the element text content, which will be displayed as the question/statement.

```mdx-code-block
<Tabs
	defaultValue="html"
	values={[
		{label: 'HTML', value: 'html'},
		{label: 'React', value: 'react'},
		{label: 'Angular', value: 'angular'},
	]}
	groupId="framework"
	queryString="framework">
<TabItem value="html">
```

```html
<ontario-hint-text>This is a hint</ontario-hint-text>
```

```mdx-code-block
</TabItem>
<TabItem value="react">
```

```tsx
<OntarioHintText>This is a hint</OntarioHintText>
```

```mdx-code-block
</TabItem>
<TabItem value="angular">
```

```html
<ontario-hint-text>This is a hint</ontario-hint-text>
```

```mdx-code-block
</TabItem>
</Tabs>
```

<OntarioHintText>This is a hint</OntarioHintText>

Example of a hint text that includes the `hint` property, which will override the `This is a hint` text. The `element-id` property has also been added, which is used to establish a relationship between hint text content and elements using the `aria-describedby` attribute.

```mdx-code-block
<Tabs
	defaultValue="html"
	values={[
		{label: 'HTML', value: 'html'},
		{label: 'React', value: 'react'},
		{label: 'Angular', value: 'angular'},
	]}
	groupId="framework"
	queryString="framework">
<TabItem value="html">
```

```html
<ontario-hint-text hint="This hint will override the hint text provided as element content" element-id="hint-293849">
	This is a hint
	<ontario-hint-text></ontario-hint-text>
</ontario-hint-text>
```

```mdx-code-block
</TabItem>
<TabItem value="react">
```

```tsx
<OntarioHintText hint="This hint will override the hint text provided as element content" elementId="hint-293849">
	This is a hint
</OntarioHintText>
```

```mdx-code-block
</TabItem>
<TabItem value="angular">
```

```html
<ontario-hint-text
	[hint]="'This hint will override the hint text provided as element content'"
	[elementId]="'hint-293849'"
>
	This is a hint
</ontario-hint-text>
```

```mdx-code-block
</TabItem>
</Tabs>
```

<div>
  <OntarioHintText hint="This hint will override the hint text provided as element content" elementId="hint-293849">
	  This is a hint
  </OntarioHintText>
</div>

## Technical Note: SSR (Server-Side Rendering) Considerations

The Ontario Hint Text component supports server-side rendering, with a few considerations:

- **Preferred content source:** Pass hint content through the `hint` 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 `hint` over slotted children.

### SSR-safe example:

```tsx
<OntarioHintText hint="Provide a detailed street address."></OntarioHintText>
```

<!-- Auto Generated Below -->

## Overview

Ontario Hint Text provides concise supporting instructions for form controls.

Use hint text to help users understand how to complete fields in a form.

For component guidance, see:

- https://designsystem.ontario.ca/components/detail/hint-text.html
- https://designsystem.ontario.ca/developer-docs/components/ontario-hint-text/

## Properties

| Property          | Attribute           | Description                                                                                                                                                                       | Type                              | Default     |
| ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------- |
| `elementId`       | `element-id`        | The unique identifier of the element. This is optional - if no ID is passed, one will be generated.                                                                               | `string \| undefined`             | `undefined` |
| `hint`            | `hint`              | Text to display as the hint text statement. Setting the hint can be done using the host element textContent or through setting this property. This property will take precedence. | `string`                          | `undefined` |
| `hintContentType` | `hint-content-type` | The content type of the hint. If no prop is passed, it will default to a string. If the hint requires multiple lines or HTML, the `hintContentType` prop should be set to `html`. | `"html" \| "string" \| undefined` | `'string'`  |

## Methods

### `getHintTextId() => Promise<string | undefined>`

This method returns the ontario-hint-text id. It is used to make sure the hint text and `aria-describedby` value of other form components match when the internal hint text props are used.

#### Returns

Type: `Promise<string | undefined>`

The ID of the hint text element, or undefined if no ID is set.

## Shadow Parts

| Part          | Description                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------- |
| `"hint-text"` | The container for the hint text content. This part can be used to apply custom styles to the hint text. |

## Dependencies

### Used by

- [ontario-checkboxes](../ontario-checkbox)
- [ontario-dropdown-list](../ontario-dropdown-list)
- [ontario-input](../ontario-input)
- [ontario-radio-buttons](../ontario-radio-buttons)
- [ontario-search-box](../ontario-search-box)
- [ontario-task](../ontario-task)
- [ontario-textarea](../ontario-textarea)

### Graph

```mermaid
graph TD;
  ontario-checkboxes --> ontario-hint-text
  ontario-dropdown-list --> ontario-hint-text
  ontario-input --> ontario-hint-text
  ontario-radio-buttons --> ontario-hint-text
  ontario-search-box --> ontario-hint-text
  ontario-task --> ontario-hint-text
  ontario-textarea --> ontario-hint-text
  style ontario-hint-text fill:#f9f,stroke:#333,stroke-width:4px
```

---

_Built with [StencilJS](https://stenciljs.com/)_