Textarea

Examples

<gl-form-textarea placeholder="Enter description" />

<gl-form-group label="Textarea" label-for="textarea-form-group">
  <gl-form-textarea id="textarea-form-group" placeholder="Enter description" />
</gl-form-group>

View in Pajamas UI Kit →

Structure

Guidelines

Appearance

Behavior

Accessibility

• When using GlFormGroup, the label prop alone does not give the input an accessible name.
• The label-for prop must also be provided to give the input an accessible name.

Textarea with label

<script>
export default {
  data() {
    return {
      description: '',
    };
  },
};
</script>

<template>
  <gl-form-group label="Issue description" label-for="issue-description">
    <gl-form-textarea id="issue-description" v-model="description" />
  </gl-form-group>
</template>

Textarea with hidden label

<script>
export default {
  data() {
    return {
      description: '',
    };
  },
};
</script>

<template>
  <gl-form-group label="Issue description" label-for="issue-description" label-sr-only>
    <gl-form-textarea id="issue-description" v-model="description" />
  </gl-form-group>
</template>

Code reference

Create multi-line text inputs with support for auto height sizing, minimum and maximum number of rows, and contextual states.

Displayed rows

To set the height of <gl-form-textarea>, set the rows prop to the desired number of rows. The minimum value is 2, and the default is 4.

Enable resize handle

By default, the resize handle is hidden (no-resize is true). To allow users to resize the textarea, set no-resize to false.

Auto height

<gl-form-textarea> can also automatically adjust its height (text rows) to fit the content, even as the user enters or deletes text. The height of the textarea will either grow or shrink to fit the content (grow to a maximum of max-rows or shrink to a minimum of rows).

To set the initial minimum height (in rows), set the rows prop to the desired number of lines (or leave it at the default of 4), and then set maximum rows that the text area will grow to (before showing a scrollbar) by setting the max-rows prop to the maximum number of lines of text.

Note that the resize handle of the textarea (if supported by the browser) will automatically be disabled in auto-height mode.

Contextual states

<gl-form-textarea> includes validation styles for valid and invalid states.

Generally speaking, you'll want to use a particular state for specific types of feedback:

• false (denotes invalid state) is great for when there's a blocking or required field. A user must fill in this field properly to submit the form.
• true (denotes valid state) is ideal for situations when you have per-field validation throughout a form and want to encourage a user through the rest of the fields.
• null: Displays no validation state (neither valid nor invalid).

Conveying contextual state to assistive technologies and colorblind users

Using these contextual states to denote the state of a form control only provides a visual, color-based indication, which will not be conveyed to users of assistive technologies - such as screen readers - or to colorblind users.

Ensure that an alternative indication of state is also provided. For instance, you could include a hint about state in the form control's <label> text itself, or by providing an additional help text block.

aria-invalid attribute

When <gl-form-textarea> has an invalid contextual state (i.e. state is false) you may also want to set the prop aria-invalid to true, or one of the supported values:

• false: No errors.
• true or 'true': The value has failed validation.
• 'grammar': A grammatical error has been detected.
• 'spelling': A spelling error has been detected.

When aria-invalid is not explicitly set, <gl-form-textarea> defaults to 'true' if the state prop is false, and to false otherwise.

Formatter support

<gl-form-textarea> optionally supports formatting by passing a function reference to the formatter prop.

Formatting (when a formatter function is supplied) occurs when the control's native input, change, and blur events fire.

The formatter function receives two arguments: the raw value of the input element, and the native event object that triggered the format (if available).

The formatter function should return the formatted value as a string.

Formatting does not occur if a formatter is not provided.

<script>
export default {
  data() {
    return {
      text: '',
    };
  },
  methods: {
    formatter(value) {
      return value.toLowerCase();
    },
  },
};
</script>

<template>
  <div>
    <gl-form-group
      label="Textarea with formatter (on input)"
      label-for="textarea-formatter"
      description="We will convert your text to lowercase instantly"
      class="mb-0"
    >
      <gl-form-textarea
        id="textarea-formatter"
        v-model="text"
        placeholder="Enter some text"
        :formatter="formatter"
      ></gl-form-textarea>
    </gl-form-group>
    <p class="mb-0"><b>Value:</b> {{ text }}</p>
  </div>
</template>

Note: If the cursor is not at the end of the input value when formatting runs, the cursor may jump to the end after a character is typed. You can use the provided event object and the event.target to access the native input's selection methods and properties to control where the insertion point is.

Readonly textarea

Set the prop readonly to style <gl-form-textarea> as readonly.

Debounce support

<gl-form-textarea> optionally supports debouncing user input, updating the v-model after a period of idle time from when the last character was entered by the user (or a change event occurs). If the user enters a new character (or deletes characters) before the idle timeout expires, the timeout is re-started.

To enable debouncing, set the prop debounce to any integer greater than zero. The value is specified in milliseconds. Setting debounce to 0 will disable debouncing.

Autofocus

When the autofocus prop is set on <gl-form-textarea>, the textarea will be auto-focused when it is inserted (i.e. mounted) into the document or re-activated when inside a Vue <keep-alive> component. Note that this prop does not set the autofocus attribute on the textarea, nor can it tell when the textarea becomes visible.

Custom classes

Use the textarea-classes prop to apply additional CSS classes to the rendered <textarea> element.

Character count

Set the character-count-limit prop to render a GlFormCharacterCount beneath the textarea, showing remaining characters or how far over the limit the value is. The textarea is automatically associated with the count via aria-describedby.

Provide internationalized labels through two scoped slots, both of which receive a count binding:

• remaining-character-count-text — text shown while the value is at or under the limit.
• character-count-over-limit-text — text shown once the value exceeds the limit.

<gl-form-textarea v-model="text" :character-count-limit="100">
  <template #remaining-character-count-text="{ count }">
    {{ n__('%d character remaining.', '%d characters remaining.', count) }}
  </template>
  <template #character-count-over-limit-text="{ count }">
    {{ n__('%d character over limit.', '%d characters over limit.', count) }}
  </template>
</gl-form-textarea>

Submit on enter

When submit-on-enter is true, <gl-form-textarea> emits a submit event when the user presses Ctrl+Enter or Cmd+Enter. This is useful for forms where Enter should insert a newline (the default textarea behavior) and a modifier key is used to submit.

Custom events

The custom update and change events receive a single argument of the current value (after any formatting has been applied), and are triggered by user interaction.

The custom input event is passed the input value, and is emitted whenever the v-model needs updating (it is emitted before update, change, and blur as needed).

The custom submit event is emitted when submit-on-enter is enabled and the user presses Ctrl+Enter or Cmd+Enter.

The custom blur event is emitted when the textarea loses focus and receives the native event object as its argument.

Public methods

<gl-form-textarea> exposes the focus and blur methods of the native textarea element on the component reference (i.e. assign a ref to your <gl-form-textarea ref="foo" ...> and use this.$refs['foo'].methodName(...)).

Refer to https://developer.mozilla.org/en-US/docs/Web/API/HTMLTextAreaElement for more information on these methods.

GlFormTextarea

import { GlFormTextarea } from '@gitlab/ui';