TextArea ​

A TextArea is a multi-line text input that allows manual resizing if needed.

Guidelines ​

Using text areas ​

This form element is useful when the user needs to enter a sizable amount of free-form text, for example comments, reviews, feedback, or short essay responses.

Use TextArea to let users enter long text that exceeds one line. Avoid using TextArea if the text to be entered is short. In this case use TextInput instead.

Specifications ​

TextArea may include the following optional elements:

1. Start icon (optional)
   Icons can simplify the identification of specific user inputs.
2. Placeholder (optional)
   The placeholder text provides an example of what type of information is being requested in the input.
3. End icon (optional)
   A secondary end icon can be included if needed.
4. Grabber (optional)
   Optionally, the grabber may be displayed to allow users the ability to vertically resize the text area as needed.

Types ​

According to the size properties, there are the following text area types:

With grabber ​

By default, a grabber will be visible, signaling to users that they can vertically resize the text area field. In this scenario, if the content cannot fit within the visible area, a scrollbar will appear to to navigate through the text that exceeds the visible area.

Use this type of text area when you require it to have a more compact size, especially in situations where it is positioned within other components like dialogs.

Autosize ​

When the autosize property is enabled, the text area’s height will be automatically resized with the length of the text. There is no need for the grabber indicator in this case, and scrolling within the content is unnecessary since the entire content will be fully visible. Choose this type of text area when there is ample space available on the page where the text area is situated.

Interaction states ​

Text areas have the following visually separate states:

Demos ​

Configurable ​

<cdx-text-area v-model="textareaValue" />

status

autosize

startIcon

endIcon

placeholder

disabled

readonly

rows

Reading direction

Default ​

The TextArea component uses v-model to two-way bind the reactive reference to the value of <textarea>. The reactive reference will automatically update when the value changes in the <textarea>. The value updates due to an emitted input event.

By default, the initial value of the autosize prop is false. When autosize is false, the textarea will display a grabber/resize tool and a scrollbar to view the overflow content. The <textarea> can be manually resized vertically to increase height of the element.

Note: The initial min-height of the <textarea> is set to 64px.

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="TextArea default demo"
		/>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxTextArea } from '@wikimedia/codex';

export default defineComponent( {
	name: 'TextAreaDefault',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( '' );

		return {
			textareaValue
		};
	}
} );
</script>

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="TextArea default demo"
		></cdx-text-area>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxTextArea } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'TextAreaDefault',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( '' );

		return {
			textareaValue
		};
	}
} );
</script>

With placeholder ​

We passed in a native attribute, placeholder, to hint to users what to enter into the control.

Note: Placeholders are not a substitute for a proper <label> element tied to the control.

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="TextArea with placeholder"
			placeholder="Start typing..."
		/>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxTextArea } from '@wikimedia/codex';

export default defineComponent( {
	name: 'TextAreaWithPlaceholder',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( '' );

		return {
			textareaValue
		};
	}
} );
</script>

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="TextArea with placeholder"
			placeholder="Start typing..."
		></cdx-text-area>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxTextArea } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'TextAreaWithPlaceholder',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( '' );

		return {
			textareaValue
		};
	}
} );
</script>

With rows ​

This example demonstrates how to pass in the native attribute, rows, to the <textarea>.

The rows attribute takes a positive number which represents the number of text lines to display in the control.

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="TextArea with rows"
			placeholder="Start typing..."
			rows="8"
		/>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxTextArea } from '@wikimedia/codex';

export default defineComponent( {
	name: 'TextAreaWithRows',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( '' );

		return {
			textareaValue
		};
	}
} );
</script>

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="TextArea with rows"
			placeholder="Start typing..."
			rows="8"
		></cdx-text-area>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxTextArea } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'TextAreaWithRows',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( '' );

		return {
			textareaValue
		};
	}
} );
</script>

With autosize ​

When the autosize prop is set to true, the TextArea automatically grows with the height of the content inside <textarea>.

The grabber/resize tool is not displayed when autosize is set to true.

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="TextArea with autosize"
			placeholder="Start typing..."
			:autosize="true"
		/>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxTextArea } from '@wikimedia/codex';

export default defineComponent( {
	name: 'TextAreaWithAutosize',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( '' );

		return {
			textareaValue
		};
	}
} );
</script>

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="TextArea with autosize"
			placeholder="Start typing..."
			:autosize="true"
		></cdx-text-area>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxTextArea } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'TextAreaWithAutosize',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( '' );

		return {
			textareaValue
		};
	}
} );
</script>

With icons ​

TextArea can pass in a start icon and end icon as props. This example shows how to add icons to the component. Also see Icon.

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="TextArea with icons"
			placeholder="Start typing..."
			:start-icon="cdxIconNotBright"
			:end-icon="cdxIconInfoFilled"
		/>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxTextArea } from '@wikimedia/codex';
import { cdxIconNotBright, cdxIconInfoFilled } from '@wikimedia/codex-icons';

export default defineComponent( {
	name: 'TextAreaWithIcons',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( '' );

		return {
			textareaValue,
			cdxIconNotBright,
			cdxIconInfoFilled
		};
	}
} );
</script>

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="TextArea with icons"
			placeholder="Start typing..."
			:start-icon="cdxIconNotBright"
			:end-icon="cdxIconInfoFilled"
		></cdx-text-area>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxTextArea } = require( '@wikimedia/codex' );
const { cdxIconNotBright, cdxIconInfoFilled } = require( './icons.json' );

// @vue/component
module.exports = defineComponent( {
	name: 'TextAreaWithIcons',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( '' );

		return {
			textareaValue,
			cdxIconNotBright,
			cdxIconInfoFilled
		};
	}
} );
</script>

With disabled ​

You can disable the component by adding the disabled attribute.

When <textarea> is disabled, the user cannot interact with the control. Users cannot click or select in the control and the form cannot be submitted.

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="Disabled TextArea"
			disabled
		/>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxTextArea } from '@wikimedia/codex';

export default defineComponent( {
	name: 'TextAreaWithDisabled',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( 'The text area is disabled.' );

		return {
			textareaValue
		};
	}
} );
</script>

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="Disabled TextArea"
			disabled
		></cdx-text-area>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxTextArea } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'TextAreaWithDisabled',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( 'The text area is disabled.' );

		return {
			textareaValue
		};
	}
} );
</script>

With readonly ​

You can make the component readonly by adding the readonly attribute.

When <textarea> is readonly, the user cannot modify the value of the control. Some key differences between disabled and readonly is that readonly does not prevent users from selecting and clicking in the form. Users can highlight and copy content in readonly. Readonly is tabbable and the form can be submitted.

One example usage of readonly textarea is when you want to prevent a user from typing into the textarea until a condition is met like selecting a a checkbox. In this situation, when the condition is met we can use JavaScript to remove the readonly to make the textarea editable.

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="Readonly TextArea"
			readonly
		/>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxTextArea } from '@wikimedia/codex';

export default defineComponent( {
	name: 'TextAreaWithReadonly',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( 'The textarea is readonly.' );

		return {
			textareaValue
		};
	}
} );
</script>

<template>
	<div>
		<cdx-text-area
			v-model="textareaValue"
			aria-label="Readonly TextArea"
			readonly
		></cdx-text-area>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxTextArea } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'TextAreaWithReadonly',
	components: { CdxTextArea },
	setup() {
		// Reactive reference to the textarea value
		const textareaValue = ref( 'The textarea is readonly.' );

		return {
			textareaValue
		};
	}
} );
</script>

Form field ​

A TextArea can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. See the Field page for more information.

<template>
	<cdx-field>
		<cdx-text-area v-model="textareaValue" placeholder="Describe what you changed" />
		<template #label>
			Edit summary
		</template>
		<template #description>
			Briefly describe your changes
		</template>
		<template #help-text>
			By saving changes, you agree to the
			<a href="https://foundation.wikimedia.org/wiki/Policy:Terms_of_Use">Terms of Use</a>,
			and you irrevocably agree to release your contribution under the
			<a href="https://creativecommons.org/licenses/by-sa/4.0/deed.en">CC BY-SA 4.0 License</a>
			and the
			<a href="https://en.wikipedia.org/wiki/Wikipedia:Text_of_the_GNU_Free_Documentation_License">GFDL</a>.
			You agree that a hyperlink or URL is sufficient attribution under the Creative Commons
			license.
		</template>
	</cdx-field>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxTextArea, CdxField } from '@wikimedia/codex';

export default defineComponent( {
	name: 'TextAreaField',
	components: { CdxTextArea, CdxField },
	setup() {
		const textareaValue = ref( '' );

		return {
			textareaValue
		};
	}
} );
</script>

<template>
	<cdx-field>
		<cdx-text-area v-model="textareaValue" placeholder="Describe what you changed"></cdx-text-area>
		<template #label>
			Edit summary
		</template>
		<template #description>
			Briefly describe your changes
		</template>
		<template #help-text>
			By saving changes, you agree to the
			<a href="https://foundation.wikimedia.org/wiki/Policy:Terms_of_Use">Terms of Use</a>,
			and you irrevocably agree to release your contribution under the
			<a href="https://creativecommons.org/licenses/by-sa/4.0/deed.en">CC BY-SA 4.0 License</a>
			and the
			<a href="https://en.wikipedia.org/wiki/Wikipedia:Text_of_the_GNU_Free_Documentation_License">GFDL</a>.
			You agree that a hyperlink or URL is sufficient attribution under the Creative Commons
			license.
		</template>
	</cdx-field>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxTextArea, CdxField } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'TextAreaField',
	components: { CdxTextArea, CdxField },
	setup() {
		const textareaValue = ref( '' );

		return {
			textareaValue
		};
	}
} );
</script>

Vue usage ​

v-model is used to track the current value of the textarea. See the events docs for details on emitted events and their properties.

Props ​

Events ​