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

# ontario-textarea

Use a text area when you want the user to enter **more than** a single line of information.

## Usage guidance

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

### Disabled and read-only states

This component intentionally does not provide `readOnly` or `disabled` props.

Disabling form controls can create accessibility and usability barriers, and often does not explain what the user needs to fix.

Instead:

- keep controls and submission actions available
- use validation and error messaging to clearly identify missing or invalid input

For implementation examples, see [Error messaging](#error-messaging).

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 textarea component can be added directly into the project's code, and can be customized by updating the properties outlined [here](#properties). Additional information on custom types for header properties are outlined [here](#custom-property-types). Please see the [examples](#examples) below for how to configure the component.

## Examples

Example of a bare-bones textarea component where the user is passing the `name` which is the value used to reference form data after a form is submitted. The `elementId` is also being passed in as the unique identifier of the textarea.

```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-textarea caption="Comments" name="comments" element-id="form-comments"></ontario-textarea>
```

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

```tsx
<OntarioTextarea caption="Comments" name="comments" elementId="form-comments"></OntarioTextarea>
```

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

```html
<ontario-textarea [caption]="'Comments'" [name]="'comments'" [elementId]="'form-comments'"></ontario-textarea>
```

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

<div>
	<OntarioTextarea caption="Comments" name="comments" elementId="form-comments"></OntarioTextarea>
</div>

To mark a textarea as required, add the `required` attribute to the component.

```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-textarea
	caption="Comments"
	name="comments"
	element-id="form-comments"
	required="true"
	onBlur="exampleFunction()"
></ontario-textarea>
```

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

```tsx
<OntarioTextarea
	caption="Comments"
	name="comments"
	elementId="form-comments"
	required={true}
	onBlur={exampleFunction}
></OntarioTextarea>
```

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

```html
<ontario-textarea
	[caption]="'Comments'"
	[name]="'comments'"
	[elementId]="'form-comments'"
	required="true"
	(onBlur)="exampleFunction()"
></ontario-textarea>
```

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

<OntarioTextarea caption="Comments" name="comments" elementId="form-comments" required={true}></OntarioTextarea>

### Forms

The `ontario-textarea` supports integration with native HTML `<form>` elements. This element integrates with the underlying browser form API and should work the same as a `<textarea>`.

The component's host `value` stays in sync as users interact with the textarea. The component updates that `value`, updates the form value, and exposes the current content through host-native events.

```html
<form>
	<!-- Add an ontario-textarea -->
	<ontario-textarea name="textarea-1" caption="Text area"></ontario-textarea>

	<!-- Submit the form with a submit button -->
	<ontario-button type="primary" html-type="submit">Submit</ontario-button>
</form>
```

Remember to set the `name` attribute as this is used to identify the field when submitting the form.

## Event model

Each event emitted by the component uses the [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) type to emit a custom event to help communicate what the component is doing. To access the data emitted by the component within the `CustomEvent` type use the [CustomEvent.detail](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail) property.

Eg. To access the value of any input entered into this component from the `inputOnInput` event, use the following code to wire up to listen for the the `inputOnInput` event.

```html
<ontario-textarea id="textarea-1" name="textarea-1" caption="Text area"></ontario-textarea>
<script>
	// Note: this waits for the page and components to load before
	// locating the component.
	window.onload = () => {
		const textarea1 = document.getElementById('textarea-1');
		textarea1.addEventListener('inputOnInput', (event) => {
			console.log('OnInput detail:', event.detail);
		});
	};
</script>
```

If the letter `i` is typed into `textarea-1`, the value of `event.detail` is the object emitted along with the `inputOnInput` event.

```js
{ id: "910b4a52-c005-4fb6-9b6e-fd7370a00b25", value: "i", inputType: "insertText" }
```

See the [Events](#events) table to learn more about the available custom events from the component and what the type of `CustomEvent.detail` will be.

### Native `input` and `change` events

The component uses a ShadowDOM to maintain encapsulation, however, this changes how the events flow from the inside of the component to the outside in the DOM.

The component keeps its `value` in sync as the internal `<textarea>`
changes.

Events, such as the native `input` event, deliver data from inside of the
component and flow up the event stack as expected.

This isn't the case for the native `change` event, this event hits the ShadowDOM boundary and stops propagating. The implication of this is that it can't be listened for outside the component. To attempt to overcome this, a synthetic change event is generated and emitted. The original `change` event is available via the `detail` property on the emitted event.

If you are observing the component from the outside, prefer reading the current textarea content from `event.target.value` on the host `input` or `change` event. Use `inputOnInput` and `inputOnChange` when you specifically want the component's richer custom event detail.

```js
document.querySelector('ontario-textarea').addEventListener('input', (event) => {
	console.log(event.target.value);
});

document.querySelector('ontario-textarea').addEventListener('change', (event) => {
	console.log(event.target.value);
});
```

When using libraries that listen for events, this process may not work with them and a workaround might be required depending on the framework or library in use.

## Error messaging

Use validation and error messaging to help users understand what needs to be corrected.

### Setting an error message

Set the `errorMessage` property on `ontario-textarea` to display an error state and message. You can also listen for `inputErrorOccurred` to react to error updates in application code.

### Static vs live validation

Use a static `errorMessage` when validation happens on submit (for example, after a form post or submit handler check).

Use live validation when you want real-time feedback as users interact (for example, on change or blur).

For more guidance, visit the [Error messaging guidance page](https://designsystem.ontario.ca/components/detail/error-messaging.html).

```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-textarea id="comments" name="comments" caption="Comments" required></ontario-textarea>
<script>
	window.addEventListener('load', () => {
		const textarea = document.getElementById('comments');
		textarea.addEventListener('inputOnBlur', () => {
			textarea.errorMessage = textarea.value?.trim() ? '' : 'Enter your comments before continuing.';
		});
	});
</script>
```

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

```tsx
<OntarioTextarea
	elementId="comments"
	name="comments"
	caption="Comments"
	required
	errorMessage="Enter your comments before continuing."
/>
```

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

```html
<ontario-textarea
	[elementId]="'comments'"
	[name]="'comments'"
	[caption]="'Comments'"
	[required]="true"
	[errorMessage]="'Enter your comments before continuing.'"
></ontario-textarea>
```

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

### Live validation

Keep the control available and validate content on interaction (for example, on blur or submit). When validation fails, set a contextual error message that explains how to fix the issue.

## Custom property types

### caption

The `caption` property is used to render the legend for the ontario-textarea. It can be passed either a string or an object. If no `captionType` needs to be specified, it can be passed as a string.

```html
caption='{ "captionText": "Textarea label", "captionType": "default" }'
```

| Property name | Type                               | Default   | Description                                                                                                                                          |
| ------------- | ---------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `captionText` | `string`                           |           | Text to display as the radio textarea question                                                                                                       |
| `captionType` | `"default" \| "large"\| "heading"` | `default` | The type of legend to display for the textarea question. This is optional, and if no information is provided, it will default to the `default` type. |

### hintExpander

The `hintExpander` property is used to include the Hint Expander component underneath the input label. This is passed in as an object with key-value pairs.

<!-- prettier-ignore -->
```html
hintExpander='{ "hint": "This is the hint expander title", "content": "This is the hint expander content - it is only visible when the hint expander title (hint) is toggled" }'
```

| Property name | Type     | Description                                                                                                     |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `hint`        | `string` | Text to display as the hint expander label/title. When toggled, it will display/hide the `hintExpander` content |
| `content`     | `string` | Text to display as the content of the hint expander                                                             |

## Accessibility

- An `element-id` attribute is necessary to allow the textarea to be associated with a label element
- A `name` attribute needs to be set to be submitted to the server when the form is submitted.

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

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

- **Language prop:** Language change events only fire in the browser after hydration. To ensure the correct language is rendered during SSR, pass the desired `language` explicitly as a prop.
- **Dynamic ID generation:** If `elementId` is not passed, a UUID is generated at runtime. To prevent hydration mismatches between server and client, explicitly pass a stable `elementId`.
- **Hint text and accessibility IDs:** If using `ontario-hint-text`, note that the `aria-describedby` reference is resolved after hydration. Make sure this does not impact critical accessibility paths in your application.
- **Form participation:** This component uses the [Form-Associated Custom Elements](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals) API (`@AttachInternals`) to participate in native form submission. During SSR, it renders with the expected `<textarea>` structure and can support straightforward form submission when `name`, `language`, and `elementId` are stable. Enhanced validation, custom validators, and the component's event model become available after hydration.
- **Hydrated-only behaviour:** If your application depends on custom events or runtime validation, use the event examples below and treat that behaviour as hydrated-only.
- **Framework guidance:** Use the HTML `<form>` example above for native submit or Next.js server-action style flows. For App Router setup details, follow the [Next.js integration guide](https://designsystem.ontario.ca/developer-docs/framework-integrations/next-js-ssr/).

### SSR-safe example:

```tsx
<OntarioTextarea name="comments" language="en" elementId="comments"></OntarioTextarea>
```

<!-- Auto Generated Below -->

## Overview

Ontario Textarea captures multi-line text input.

This component intentionally does not expose `readOnly` or `disabled` props.

To support accessible and understandable form completion:

- keep form fields and submission actions available
- use validation and error messaging to guide corrections

For component guidance, see:

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

Disabled/read-only policy source:

- https://designsystem.ontario.ca/components/detail/buttons.html#disabled-buttons

## Properties

| Property         | Attribute          | Description                                                                                                                                                                                                                                    | Type                                    | Default     |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------- |
| `caption`        | `caption`          | The text to display as the textarea label.                                                                                                                                                                                                     | `Caption \| string`                     | `undefined` |
| `customOnBlur`   | `custom-on-blur`   | Used to add a custom function to the textarea onBlur event.                                                                                                                                                                                    | `((event: Event) => void) \| undefined` | `undefined` |
| `customOnChange` | `custom-on-change` | Used to add a custom function to the textarea onChange event.                                                                                                                                                                                  | `((event: Event) => void) \| undefined` | `undefined` |
| `customOnFocus`  | `custom-on-focus`  | Used to add a custom function to the textarea onFocus event.                                                                                                                                                                                   | `((event: Event) => void) \| undefined` | `undefined` |
| `customOnInput`  | `custom-on-input`  | Used to add a custom function to the textarea onInput event.                                                                                                                                                                                   | `((event: Event) => void) \| undefined` | `undefined` |
| `elementId`      | `element-id`       | The unique identifier of the textarea. This is optional - if no ID is passed, one will be generated.                                                                                                                                           | `string \| undefined`                   | `undefined` |
| `errorMessage`   | `error-message`    | Set this to display an error message                                                                                                                                                                                                           | `string \| undefined`                   | `undefined` |
| `hintExpander`   | `hint-expander`    | Used to include the ontario-hint-expander component for the textarea component. This is passed in as an object with key-value pairs. This is optional.                                                                                         | `HintExpander \| string \| undefined`   | `undefined` |
| `hintText`       | `hint-text`        | Used to include the ontario-hint-text component for the textarea. This is optional.                                                                                                                                                            | `Hint \| string \| undefined`           | `undefined` |
| `language`       | `language`         | The language of the component. This is used for translations, and is by default set through event listeners checking for a language property from the header. If no language is passed, it will default to English.                            | `"en" \| "fr" \| undefined`             | `undefined` |
| `name`           | `name`             | The name assigned to the textarea. The name value is used to reference form data after a form is submitted.                                                                                                                                    | `string`                                | `undefined` |
| `required`       | `required`         | This is used to determine whether the textarea is required or not. This prop also gets passed to the InputCaption utility to display either an optional or required flag in the label. If no prop is set, it will default to false (optional). | `boolean \| undefined`                  | `false`     |
| `value`          | `value`            | The textarea content value.                                                                                                                                                                                                                    | `string \| undefined`                   | `undefined` |

## Events

| Event                | Description                                                                         | Type                                                                        |
| -------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `inputErrorOccurred` | Emitted when an error message is reported to the component.                         | `CustomEvent<{ inputId: string; errorMessage: string; }>`                   |
| `inputOnBlur`        | Emitted when a keyboard input event occurs when an input has lost focus.            | `CustomEvent<InputInteractionEvent & { focused: boolean; }>`                |
| `inputOnChange`      | Emitted when a keyboard input or mouse event occurs when an input has been changed. | `CustomEvent<{ id?: string \| undefined; value?: string \| undefined; }>`   |
| `inputOnFocus`       | Emitted when a keyboard input event occurs when an input has gained focus.          | `CustomEvent<InputInteractionEvent & { focused: boolean; }>`                |
| `inputOnInput`       | Emitted when a input event occurs when an input has been changed.                   | `CustomEvent<InputInteractionEvent & { inputType?: string \| undefined; }>` |

## Dependencies

### Depends on

- [ontario-hint-text](../ontario-hint-text)
- [ontario-hint-expander](../ontario-hint-expander)
- [ontario-icon-alert-error](../ontario-icon)

### Graph

```mermaid
graph TD;
  ontario-textarea --> ontario-hint-text
  ontario-textarea --> ontario-hint-expander
  ontario-textarea --> ontario-icon-alert-error
  ontario-hint-expander --> ontario-icon-chevron-up
  ontario-hint-expander --> ontario-icon-chevron-down
  style ontario-textarea fill:#f9f,stroke:#333,stroke-width:4px
```

---

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