jb-textarea

Simple textarea web component to input long text

• lightweight
• zero dependency
• advance validation with jb-validation module
• help you manage validation in easy way
• config auto height grow ability with max height
• web component so you can use it with any framework you need

When to use

Use jb-textarea when the user needs to enter multi-line text, long descriptions, comments, notes, or any free-form text that can span multiple lines. See the basic textarea demo for the default interaction.

Use jb-input for single-line text fields.

Demo

• Explore the textarea examples, including validation, auto-height and state binding, custom slots, and events.
• Try the standalone CodePen example.

Using With JS Frameworks

Other integrations: Angular · Vue · Nuxt · Svelte · SvelteKit · SolidJS · Lit · Next.js · Astro · Blazor · Server-rendered templates · WordPress · Alpine.js and HTMX

Installation

npm i jb-textarea

<jb-textarea label="description" value="" message="text under the textarea box"></jb-textarea>

API reference

Attributes

| name | type | default | description | | --- | --- | --- | --- | | value | string | "" | Initial textarea value from markup. Prefer the property for runtime updates; see the value demo. | | label | string | "" | Visible label text and accessible aria label; see the normal textarea. | | message | string | "" | Helper text shown below the textarea when no validation error is visible. | | name | string | "" | Form field name. | | placeholder | string | "" | Placeholder forwarded to the inner textarea; see the RTL demo. | | required | boolean | false | Enables required validation; see the required demo. | | error | string | "" | External validation error message; see the error demo. |

Properties

| name | type | readonly | description | | --- | --- | --- | --- | | value | string | no | Canonical textarea value submitted with forms; see controlled values. | | autoHeight | boolean | no | Lets the textarea grow between configured min and max height; see the auto-height demo. | | validation | ValidationHelper<string> | yes | Validation helper from jb-validation; set validation.list for custom rules. | | disabled | boolean | no | Disables the inner textarea and sets the disabled custom state; see disabled. | | required | boolean | no | Enables required validation; see required validation. | | initialValue | string | no | Default and reset value. It initializes value until the live value is explicitly set; see initial value. | | isDirty | boolean | yes | true when current value differs from initialValue. | | validationMessage | string | yes | Current native validation message from ElementInternals. |

Methods

| name | returns | description | | --- | --- | --- | | checkValidity() | boolean | Runs validation without showing the error message. Dispatches invalid when invalid; see the event demo. | | reportValidity() | boolean | Runs validation and shows the first error message. Dispatches invalid when invalid; see validation. | | reset() | void | Restores initialValue and clears displayed validation. |

get and set value

Read or assign .value for runtime text; see the normal value demo, initial/reset flow, and controlled value precedence.

document.querySelector("jb-textarea").value;
// return inputted text
document.querySelector("jb-textarea").value = "hello";
set value to hello

set validation

Use required, error, or validation.list for validation; see the required, error, and custom validation demos.

jb-textarea use jb-validation inside to handle validation so for more information you can read it's documentation.
for simple usage you can set validation to your input:

//you have 2 ways: 
//1- set list directly 
    description.validation.list = [
        {
            validator: /.{3}/g,
            message: 'description must have 3 char at least'
        },
    //you can use function as a validator too
        {
            validator: (valueString)=>{return valueString == "hello"},
            message: 'you can only type hello in the box'
        },
    //you can also return string in validator if you want custom error message in some edge cases
        {
            validator: (valueString)=>{
               if(valueString.includes("*")){
                return 'you cant write * in your text'
               }
               return true;
            },
            message: 'default error when return false'
        },
    ];
//2- pass a function that returns the validation list so on each validation process we execute your callback function and get the needed validation list
const result = document.querySelector('jb-textarea').validation.addValidationListGetter(getterFunction)

check validation

Call checkValidity() for a silent result or reportValidity() to show the first validation error; see the event/validation demo.

like any other jb design system you can access validation by validation property:

//access validation module
document.querySelector('jb-textarea').validation
// check if input pass all the validations. showError is a boolean that determine your intent to show error to user on invalid status.
const result = document.querySelector('jb-textarea').validation.checkValidity({showError})

Events

| event | cancelable | when it fires | | --- | --- | --- | | input | native behavior | On each user edit after value is updated; see the event demo. | | beforeinput | yes | Before the inner textarea value changes. Call event.preventDefault() to block the edit; see events. | | change | yes | When the user commits the textarea value; see events. | | keydown | yes | Re-dispatched from the inner textarea; see events. | | keyup | yes | Re-dispatched from the inner textarea; see events. | | keypress | yes | Re-dispatched from the inner textarea; see events. | | enter | yes | From keypress when Enter is pressed; see the Enter demo. | | invalid | no | When checkValidity() or reportValidity() finds an invalid value; see validation. |

React users receive these events through the React wrapper: onChange is a React change event and onChangeNative receives this raw native change event. See the React documentation.

document.querySelector("jb-textarea").addEventListener('change',func);
document.querySelector("jb-textarea").addEventListener('keydown',func);
document.querySelector("jb-textarea").addEventListener('keyup',func);
document.querySelector("jb-textarea").addEventListener('keypress',func);
document.querySelector("jb-textarea").addEventListener('input',func);
// custom Keyboard event that raise when user press enter (unlike jb-input this enter event raise after keypress because it could be cancelled with prevent default)
document.querySelector("jb-textarea").addEventListener('enter',func);

auto height grow

Set autoHeight to grow between the configured CSS min/max heights; see the auto-height demo.

document.querySelector("jb-textarea").autoHeight = true;

the good point of set boundary with CSS variable is you can set different min or max based on device by CSS media queries.

RTL

Use the same labels and placeholders in right-to-left layouts; see the RTL demo.

set custom style

you have 2 way to customize style,

1. using selectors like:states or ::part selector

jb-textarea::part(label){
  font-size: 2rem;
}
jb-textarea:states(invalid)::part(label){
  color:red;
}
jb-textarea:states(invalid)::part(control){
  border-color:red;
}
jb-textarea:states(disabled)::part(textarea){
  cursor:not-allowed;
}

we have label, control, textarea, message, inline-start-wrapper, inline-end-wrapper, block-start-wrapper, and block-end-wrapper as supported parts in our component. you can also combine them with disabled, invalid states for different style in different states.

2. using CSS variable

For complete styling guidance, live examples, official parts, custom states, and copyable style recipes, see Styling and the style gallery.

add custom element in textarea box

in jb-textarea you can put icon or any other custom html DOM in textarea box. to doing so you just have to place custom DOM in jb-textarea tag and add slot="inline-start" or slot="inline-end" or slot="block-start" or slot="block-end" to place it before or after input field. See the inline-start, inline-end, block-start, and block-end demos.

| slot | description | | --- | --- | | inline-start | Inline content before the textarea. | | inline-end | Inline content after the textarea. | | block-start | Block content above the textarea inside the textarea box. | | block-end | Block content below the textarea inside the textarea box. |

example:

<jb-textarea>
    <div slot="inline-start">before</div>
    <div slot="inline-end">after</div>
    <div slot="block-start">in Top</div>
    <div slot="block-end">in Bottom</div>
</jb-textarea>

Accessibility notes

• The component is form-associated and submits value as its form value.
• label is exposed as the component aria label.
• message is exposed as the component aria description when no validation error is visible.
• placeholder is forwarded to the inner textarea and exposed as aria placeholder.
• disabled, invalid, and validation state are synchronized with ElementInternals where the browser supports it.
• The shadow root uses delegatesFocus, so focusing <jb-textarea> focuses the inner native textarea.

Related Docs

• see jb-textarea/react if you want to use this component in react.

• see All JB Design system Component List for more components.

• use Contribution Guide if you want to contribute in this component.

AI agent notes

This package includes custom-elements.json so documentation tools, IDEs, and AI coding agents can discover the tag name, attributes, properties, events, slots, CSS parts, CSS variables, and public methods.

The package also exposes "customElements": "custom-elements.json" in package.json, which gives tools a stable package-level pointer to the manifest. This field is documented by the Custom Elements Manifest project in its Referencing manifests from npm packages section.

In custom-elements.json, the exports array describes what this module makes available:

| kind | meaning | | --- | --- | | js | A JavaScript/TypeScript export from the module, such as JBTextareaWebComponent. | | custom-element-definition | The custom element registration for a tag name, such as jb-textarea. |

• Import jb-textarea once before using <jb-textarea>.
• Use jb-textarea for multi-line text and jb-input for single-line text.
• Use .value for the canonical submitted text.
• Use autoHeight when the textarea should grow with content, and control bounds with --jb-textarea-min-height and --jb-textarea-max-height.
• Set error for externally controlled validation errors; the component observes the attribute and updates its validation UI.