Textarea

Textarea Specification

• Textarea Specification
  • Owned by
  • Requires approval from
  • Signed off by
  • Revision History
  • Overview
    • Acceptance criteria
  • User stories
  • Functionality
    • End-User Experience
    • Developer Experience
      • Initialization
      • Value binding through attribute
      • Value binding through content projection
      • Form integration with prefix content
    • Localization
    • Keyboard navigation
  • API
    • Properties
    • Methods
    • Events
    • Slots
    • CSS Shadow Parts
  • Test scenarios
  • Accessibility
    • ARIA
    • RTL Support
  • Assumptions and Limitations

Owned by

Web Development Team

Developer Name

1. Radoslav Karaivanov

Designer Name

1. Silvia Ivanova

Requires approval from

• Simeon Simeonoff | Date:
• Svilen Dimchevski | Date:

Signed off by

• Radoslav Mirchev | Date:
• Damyan Petev | Date:

Revision History

Version	Users	Date	Notes
1	Radoslav Karaivanov	2023-09-20
1.1	Radoslav Karaivanov	2024-04-29	Added validateOnly

Overview

The <igx-textarea> represents a multi-line plain-text editing control, useful when you want to allow users to enter a sizeable amount of free-form text, for example a comment on a review or feedback form.

Acceptance criteria

1. Should be able to initialize and update the value both through attribute/property and text projection.
2. Should participate in form submission and form validation.

User stories

Developer stories:

As a developer I expect to be able to:

• set a name attribute so that the control is identifiable in the context of a web form
• set a value so that the control can be programmatically initialized or updated
• set a value by slotting in text content in the control
• set a required attribute so that the control becomes mandatory in the context of a web form
• set a minlength attribute so that the control validates the minimum length of the provided value
• set a maxlength attribute so that the control validates the maximum length of the provided value
• set a disabled attribute so that the control can't be modified or interacted with
• set a readonly attribute so that the control can't be modified
• set a label attribute so that the user would know what to enter and easily differentiate between several components placed on the same page
• set a placeholder so that the user has a hint or an example of what to enter as a value
• slot content as a prefix/suffix so I can make more involved scenarios where icons/text/etc. are used as additional visual indication
• slot content as a helper text part so I can provide the end-user with additional guidance, validation state, etc.
• alter between filled and outlined styles in the context of Material styled view
• use the control in a native form

End-user stories:

As an end-user I expect to be able to:

• enter text in a multi-line editing field so I can provide data to a standard web form or other parts of an application
• have a visual indicator, such as an outline so that I when the control is on focus
• have different visual states so that I know how to interact with the control
• a label so that I can identify the control
• see helper text so that I get updates about my input such as counters, validation states, etc.
• have an asterisk glyph in the label so that I know that the control is required
• have prefix/suffix slots so that I can have more context for the purpose of the control

Functionality

End-User Experience

Design hand-off

Developer Experience

The igc-textarea wraps a native textarea element inside its shadow DOM. As such it supports most of the attributes exposed by the native textarea element.

Binding a value to the igc-textarea is achieved either through the value attribute, or through slotting text in its default slot (similar to the native element).

If both are used, the slotted value takes precedence over the attribute value.

Form integration

The igc-textarea is a form associated custom element. When a name attribute is set and the component is placed inside a form parent, it will participate in the parent form submission and validation.

Initialization

<igc-textarea></igc-textarea>

Value binding through attribute

<igc-textarea value="Hello"></igc-textarea>

Value binding through content projection

<igc-textarea>Hello</igc-textarea>

Form integration with prefix content

<form>
  <igc-textarea required name="comment" label="Your comment">
    <igc-icon name="write-comment" aria-hidden="true"></igc-icon>
  </igc-textarea>
</form>

Localization

No specific points are applicable for localization.

Keyboard navigation

No additional implementation is required.

API

Properties

Property	Attribute	Modifiers	Type	Default	Description
autocapitalize	autocapitalize		"none" | "off" | "on" | "sentences" | "words" | "characters"		Controls whether and how text input is automatically capitalized as it is entered/edited by the user. MDN documentation.
autocomplete	autocomplete		string		Specifies what if any permission the browser has to provide for automated assistance in filling out form field values, as well as guidance to the browser as to the type of information expected in the field. Refer to this page for additional information.
disabled	disabled		boolean	false	The disabled state of the component
form		readonly			Returns the HTMLFormElement associated with this element.
inputMode	inputmode		"numeric" | "none" | "decimal" | "tel" | "search" | "email" | "url" | "text"		Hints at the type of data that might be entered by the user while editing the element or its contents. This allows a browser to display an appropriate virtual keyboard. MDN documentation
invalid	invalid		boolean	false	Control the validity of the control.
label	label		string		The label for the control.
maxLength	maxlength		number		The maximum number of characters (UTF-16 code units) that the user can enter. If this value isn't specified, the user can enter an unlimited number of characters.
minLength	minlength		number		The minimum number of characters (UTF-16 code units) required that the user should enter.
name	name		string		The name attribute of the control.
outlined	outlined		boolean	false	Whether the control will have outlined appearance.
placeholder	placeholder		string		The placeholder attribute of the control.
readOnly	readonly		boolean	false	Makes the control a readonly field.
required	required		boolean	false	Makes the control a required field in a form context.
resize	resize		"vertical" | "none" | "auto"	"vertical"	Controls whether the control can be resized. When auto is set, the control will try to expand and fit its content.
rows	rows		number	2	The number of visible text lines for the control. If it is specified, it must be a positive integer. If it is not specified, the default value is 2.
spellcheck	spellcheck		boolean	true	Controls whether the element may be checked for spelling errors.
validationMessage		readonly			A string containing the validation message of this element.
validity		readonly			Returns a ValidityState object which represents the different validity states the element can be in, with respect to constraint validation.
value	value		string	""	The value of the component
willValidate		readonly			A boolean value which returns true if the element is a submittable element that is a candidate for constraint validation.
wrap	wrap		"off" | "hard" | "soft"	"soft"	Indicates how the control should wrap the value for form submission. Refer to this page on MDN for explanation of the available values.
validateOnly	validate-only		boolean	false	Enables validation rules to be evaluated without restricting user input. This applies to the maxLength property when it is defined.

Methods

Method	Type	Description
checkValidity	(): any	Checks for validity of the control and emits the invalid event if it invalid.
reportValidity	(): any	Checks for validity of the control and shows the browser message if it invalid.
scrollTo	{ (options?: ScrollToOptions | undefined): void; (x: number, y: number): void; }
select	(): void	Selects all text within the control.
setCustomValidity	(message: string): void	Sets a custom validation message for the control. As long as message is not empty, the control is considered invalid.
setRangeText	(replacement: string, start: number, end: number, selectMode?: "start" | "end" | "select" | "preserve"): void	Replaces the selected text in the control.
setSelectionRange	(start: number, end: number, direction?: "backward" | "forward" | "none"): void	Sets the text selection range of the control

Events

Event	Description
igcBlur	Emitted when the control loses focus.
igcChange	Emitted when the a change to the control value is committed by the user.
igcFocus	Emitted when the control gains focus.
igcInput	Emitted when the control receives user input.

Slots

Name	Description
	Text content from the default slot will be used as the value of the component.
helper-text	Renders content below the input.
prefix	Renders content before the input.
suffix	Renders content after input.

CSS Shadow Parts

Part	Description
container	The main wrapper that holds all main input elements.
helper-text	The helper text wrapper.
input	The native input element.
label	The native label element.
prefix	The prefix wrapper.
suffix	The suffix wrapper.

Test scenarios

Automation

• Should initialize and render an igc-textarea.
• Should be able to set the value through an attribute.
• Should be able to set the value through projected text content in the default slot.
• Projected text content should take precedence over the value attribute.
• DOM mutations of the projected content should be reflected in the value of the component.
• Should emit input event when typing in the component.
• Should emit change event when an edit of the value is done.
• Should support the standard API for text-based inputs.
• Should integrate into form submission and validation.

Accessibility

ARIA

• the internal textarea should have an aria-invalid attribute bound to the validity state of the control.

RTL Support

The component should work in Right to Left context without additional configuration.

Assumptions and Limitations

Due to how the shadow DOM is structured, the component does not expose a cols attribute. Horizontal sizing is achieved through CSS.