Since Shoelace 2.0 Code stable Pattern stable Figma ready

Textarea

sl-textarea

Textareas collect data from the user and allow multiple lines of text.

Examples

Basic Textarea with Label

Use the label attribute to give the textarea an accessible label.

<sl-textarea label="Month in review"></sl-textarea>

sl-textarea label="Month in review"

= ts_form_for ... do |f|
  = f.input :month_in_review,
    as: :text,
    input_html: {
      label: "Month in review"
    }

import SlTextarea from '@teamshares/shoelace/dist/react/textarea';

const App = () => <SlTextarea />;

Help Text

Add descriptive help text to a textarea with the help-text attribute. For help text that contains HTML, use the help-text slot instead.


Tell us the highlights. Be sure to include details about any financial performance anomalies. 
<sl-textarea label="Month in review" help-text="Tell us the highlights. Be sure to include details about any financial performance anomalies."> </sl-textarea>
<br />
<sl-textarea label="Month in review">
  <div slot="help-text">Tell us the highlights. Be sure to include details about any financial performance <strong>anomalies</strong>.</div>
</sl-textarea>

sl-textarea[
  label="Month in review"
  help-text="Tell us the highlights. Be sure to include details about any financial performance anomalies."
]
br
sl-textarea label="Month in review"
  div slot="help-text"
    | Tell us the highlights. Be sure to include details about any financial performance
    strong anomalies
    | .

= ts_form_for ... do |f|
  = f.input :month_in_review,
    as: :text,
    input_html: {
      label: "Month in review",
      "help-text": "Tell us the highlights. Be sure to include details about any financial performance anomalies.",
    }

import SlTextarea from '@teamshares/shoelace/dist/react/textarea';

const App = () => <SlTextarea label="Feedback" help-text="Please tell us what you think." />;

Label with Tooltip

Use the label-tooltip attribute to add text that appears in a tooltip triggered by an info icon next to the label. 

<sl-textarea label="Month in review" help-text="Tell us the highlights. Be sure to include details about any financial performance anomalies." label-tooltip="There is no required format for this commentary. However, we suggest covering the following topics: 1) Revenue, 2) COGS, 3) Gross profit, and 4) Operating expenses."></sl-textarea>

sl-textarea[
  label="Month in review"
  help-text="Tell us the highlights. Be sure to include details about any financial performance anomalies."
  label-tooltip="There is no required format for this commentary. However, we suggest covering the following topics: 1) Revenue, 2) COGS, 3) Gross profit, and 4) Operating expenses."
]

= ts_form_for ... do |f|
  = f.input :month_in_review,
    as: :text,
    input_html: { \
      label: "Month in review",
      "help-text": "Tell us the highlights. Be sure to include details about any financial performance anomalies.",
      "label-tooltip": "There is no required format for this commentary. However, we suggest covering the following topics: 1) Revenue, 2) COGS, 3) Gross profit, and 4) Operating expenses.",
    }

import SlTextarea from '@teamshares/shoelace/dist/react/textarea';

const App = () => <SlTextarea label="Comments" />;

Label with Context Note

Use the context-note attribute to add text that provides additional context or reference. For text that contains HTML, use the context-note slot. Note: On small screens the context note will wrap below the label if there isn’t enough room next to the label. 

<sl-textarea label="Month in review" help-text="Tell us the highlights. Be sure to include details about any financial performance anomalies." context-note="Data synced 1 hr ago"></sl-textarea>

sl-textarea[
  label="Month in review"
  help-text="Tell us the highlights. Be sure to include details about any financial performance anomalies."
  context-note="Data synced 1 hr ago"
]

/*
  — NOTE: Slots are not supported with ts_form_for —
*/
= ts_form_for ... do |f|
  = f.input :month_in_review,
    as: :text,
    input_html: { \
      label: "Month in review",
      "help-text": "Tell us the highlights. Be sure to include details about any financial performance anomalies.",
      "context-note": "Data synced 1 hr ago",
    }

import SlTextarea from '@teamshares/shoelace/dist/react/textarea';

const App = () => <SlTextarea label="Comments" />;

Rows

Use the rows attribute to change the number of text rows that the textarea shows before the text starts to overflow and the textarea scrolls. 



<sl-textarea label="Textarea with 2 rows" rows="2"></sl-textarea>
<br />
<sl-textarea label="Textarea with 4 rows (Default)" rows="4"></sl-textarea>
<br />
<sl-textarea label="Textarea with 6 rows" rows="6"></sl-textarea>

sl-textarea[
  label="Textarea with 2 rows"
  rows="2"
]
br
sl-textarea[
  label="Textarea with 4 rows (Default)"
  rows="4"
]
br
sl-textarea[
  label="Textarea with 6 rows"
  rows="6"
]

= ts_form_for ... do |f|
  = f.input :rows_2,
    as: :text,
    input_html: {
      label: "Textarea with 2 rows",
      rows: "2",
    }
  = f.input :rows_4,
    as: :text,
    input_html: {
      label: "Textarea with 4 rows (Default)",
      rows: "4",
    }
  = f.input :rows_6,
    as: :text,
    input_html: {
      label: "Textarea with 6 rows",
      rows: "6",
    }

import SlTextarea from '@teamshares/shoelace/dist/react/textarea';

const App = () => <SlTextarea rows={2} />;

Disabled

Use the disabled attribute to disable a textarea.

<sl-textarea label="Disabled textarea" disabled></sl-textarea>

sl-textarea[
  label="Disabled textarea"
  disabled=true
]

= ts_form_for ... do |f|
  = f.input :disabled_textarea,
    as: :text,
    input_html: {
      label: "Disabled textarea",
      disabled: true,
    }

import SlTextarea from '@teamshares/shoelace/dist/react/textarea';

const App = () => <SlTextarea placeholder="Textarea" disabled />;

Prevent Resizing

By default, textareas can be resized vertically by the user. To prevent resizing, set the resize attribute to none. 

<sl-textarea label="Textarea with no resizing" resize="none"></sl-textarea>

sl-textarea[
  label="Textarea with no resizing"
  resize="none"
]

/*
  — NOTE: In ts_form_for resize="auto" is the default —
  — Use resize="vertical" to match the Shoelace default —
*/
= ts_form_for ... do |f|
  = f.input :no_resizing,
    as: :text,
    input_html: {
      label: "Textarea with no resizing",
      resize: "none",
    }

import SlTextarea from '@teamshares/shoelace/dist/react/textarea';

const App = () => <SlTextarea resize="none" />;

Expand with Content

Textareas will automatically resize to expand to fit their content when resize is set to auto. 

<sl-textarea label="Expanding textarea" resize="auto" value="Someone’s sitting in the shade today because someone planted a tree a long time ago. ... Keep typing to see the textarea expand..." rows="2"></sl-textarea>

sl-textarea[
  label="Expanding textarea"
  resize="auto"
  value="Someone’s sitting in the shade today because someone planted a tree a long time ago. ... Keep typing to see the textarea expand..."
  rows="2"
]

/*
  — NOTE: In ts_form_for resize="auto" is the default —
  — Use resize="vertical" to match the Shoelace default —
*/
= ts_form_for ... do |f|
  = f.input :expanding,
    as: :text,
    input_html: {
      label: "Textarea with no resizing",
      label: "Expanding textarea",
      resize: "auto",
      value: "Someone’s sitting in the shade today because someone planted a tree a long time ago. ... Keep typing to see the textarea expand...",
      rows: "2",
    }

import SlTextarea from '@teamshares/shoelace/dist/react/textarea';

const App = () => <SlTextarea resize="auto" />;

Usage

Testing

With Cypress

Adding data-test-id to a component

To test sl-textarea, add the data-test-id attribute directly to the component: 

  sl-textarea[
    label="Bio"
    data-test-id="textarea-test"
  ]

To test sl-textarea implemented with ts_form_for, add data-test-id to input_html: 

  = ts_form_for ... do |f|
    = f.input :textarea_name, 
      as: :text,
      input_html: { 
        label: "Bio",
        data: { 
          test_id: "textarea-test"
        } 
      }

Cypress commands for sl-textarea

To type in the textarea:

  cy.slTextAreaType(`[data-test-id="textarea-test"]`, "This is long text to type into the textarea for testing.");

To check the textarea’s value (note the matcher "have.value"):

  cy.get(`[data-test-id="textarea-test"]`).should("have.value", "This is the long text value we want the textarea to have.");

To focus on the textarea:

  cy.slFocus(`[data-test-id="textarea-test"]`);

To clear the textarea:

  cy.slTextAreaClear(`[data-test-id="textarea-test"]`);

Component Props

Property Default Details
name ''

string

The name of the textarea, submitted as a name/value pair with form data.
value ''

string

The current value of the textarea, submitted as a name/value pair with form data.
size 'medium'

'small' | 'medium' | 'large'

The textarea’s size.
filled false

boolean

Draws a filled textarea.
label ''

string

The textarea’s label. If you need to display HTML, use the label slot instead.
labelTooltip
label-tooltip 		''

string

Text that appears in a tooltip next to the label. If you need to display HTML in the tooltip, use the label-tooltip slot instead.

contextNote
context-note 		''

string

Text that appears above the textarea, on the right, to add additional context. If you need to display HTML in this text, use the context-note slot instead.

helpText
help-text 		''

string

The textarea’s help text. If you need to display HTML, use the help-text slot instead.

placeholder ''

string

Placeholder text to show as a hint when the input is empty.
rows 4

number

The number of rows to display by default.
resize 'vertical'

'none' | 'vertical' | 'auto'

Controls how the textarea can be resized.
disabled false

boolean

Disables the textarea.
readonly false

boolean

Makes the textarea readonly.
form ''

string

By default, form controls are associated with the nearest containing <form> element. This attribute allows you to place the form control outside of a form and associate it with the form that has this id. The form must be in the same document or shadow root for this to work.

required false

boolean

Makes the textarea a required field.
minlength —

number

The minimum length of input that will be considered valid.
maxlength —

number

The maximum length of input that will be considered valid.
autocapitalize —

'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters'

Controls whether and how text input is automatically capitalized as it is entered by the user.

autocorrect —

string

Indicates whether the browser’s autocorrect feature is on or off.
autocomplete —

string

Specifies what permission the browser has to provide assistance in filling out form field values. Refer to this page on MDN for available values.

autofocus —

boolean

Indicates that the input should receive focus on page load.
enterkeyhint —

'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send'

Used to customize the label or icon of the Enter key on virtual keyboards.
spellcheck true

boolean

Enables spell checking on the textarea.
inputmode —

'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url'

Tells the browser what type of data will be entered by the user, allowing it to display the appropriate virtual keyboard on supportive devices.

defaultValue ''

string

The default value of the form control. Primarily used for resetting the form control.
validity —

—

Gets the validity state object
validationMessage —

—

Gets the validation message
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Slots

Name Details
label The textarea’s label. Alternatively, you can use the label attribute.
label-tooltip Used to add text that is displayed in a tooltip next to the label. Alternatively, you can use the label-tooltip attribute.
context-note Used to add contextual text that is displayed above the textarea, on the right. Alternatively, you can use the context-note attribute.
help-text Text that describes how to use the input. Alternatively, you can use the help-text attribute.

Learn more about using slots.

Events

Name Name Name React Event Details
sl-blur sl-blur sl-blur onSlBlur

Emitted when the control loses focus.
sl-change sl-change sl-change onSlChange

Emitted when an alteration to the control’s value is committed by the user.
sl-focus sl-focus sl-focus onSlFocus

Emitted when the control gains focus.
sl-input sl-input sl-input onSlInput

Emitted when the control receives input.
sl-invalid sl-invalid sl-invalid onSlInvalid

Emitted when the form control has been checked for validity and its constraints aren’t satisfied.

Learn more about events.

Methods

Name Details
focus()

options: FocusOptions

Sets focus on the textarea.
blur()

Removes focus from the textarea.
select()

Selects all the text in the textarea.
scrollPosition()

position: { top?: number; left?: number }

Gets or sets the textarea’s scroll position.
setSelectionRange()

selectionStart: number , selectionEnd: number , selectionDirection: 'forward' | 'backward' | 'none'

Sets the start and end positions of the text selection (0-based).
setRangeText()

replacement: string , start: number , end: number , selectMode: 'select' | 'start' | 'end' | 'preserve'

Replaces a range of text with a new string.
checkValidity()

Checks for validity but does not show a validation message. Returns true when valid and false when invalid.

getForm()

Gets the associated form, if one exists.
reportValidity()

Checks for validity and shows the browser’s validation message if the control is invalid.
setCustomValidity()

message: string

Sets a custom validation message. Pass an empty string to restore validity.

Learn more about methods.

CSS Parts

Name Description
form-control The form control that wraps the label, input, and help text.
form-control-label The label’s wrapper.
form-control-input The input’s wrapper.
form-control-help-text The help text’s wrapper.
base The component’s base wrapper.
textarea The internal <textarea> control.

Learn more about customizing CSS parts.