Textarea

Textarea Specification

Owned by

Web Development Team

Developer Name

1. Radoslav Karaivanov

Designer Name

1. ...

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	Initial version of the specification	Date

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

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

Describe behavior, design, look and feel of the implemented feature. Always include visual mock-up

End-User Experience

** Integration scenarios or functionality with other features/components prototype > ** End-to-end user experienceprototype > ** Prepared design files for styling e.g. interplay with features and light/dark variants design hand-off

Developer Experience

Globalization/Localization

No specific points are applicable for localization.

Keyboard Navigation

No specific keyboard handling is applicable.

⚠️ R.K.: Bugs in the current PR

• When the textarea is in a disabled form ancestor, fieldset for example, the disabled visual styles are not correctly applied.
• The rows attribute currently does not work as expected, since the group has a set of fixed values based on the theme for its height. This should be fixed and setting rows should control the height of the component.
• When resizing is set to auto (no scrollbar and auto-growing height) there is still a scrollbar shown in the bootstrap theme.

API

Mixins: EventEmitterMixin

Properties

Property	Attribute	Type	Default	Description
cols	cols	number	20	The visible width of the text control, in average character widths. If it is specified, it must be a positive integer. If it is not specified, the default value is 20.
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.
placeholder	placeholder	string		The placeholder attribute of the control.
resize	resize	"vertical" | "horizontal" | "auto" | "none" | "both"	"both"
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.
value	value	string	""	The value of the component

⚠️ R.K.: Since the width of the textarea is controlled by the theme, it may be ok to drop the cols property as it does nothing currently.

Methods

Method	Type	Description
blur	(): void	Removes focus from the control.
focus	(options?: FocusOptions | undefined): void	Sets focus on the control.
scrollTo	(_args: unknown): void	Relevant enough to be exposed??
select	(): void	Selects all text within the control.
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
helper-text	Renders content below the input.
prefix	Renders content before the input.
suffix	Renders content after input.

Test scenarios

Automation

Accessibility

ARIA

RTL Support

By default, the component should work in RTL environment without additional configuration.

Assumptions and Limitations