# Textarea Autoheight

Automatically sets the height of the textarea.

[![npm](https://img.shields.io/badge/npm-v4.2.0-blue)](https://www.npmjs.com/package/@preline/textarea-auto-height) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Demo](https://img.shields.io/badge/demo-online-brightgreen)](https://preline.co/plugins/textarea-autoheight.html)

## Contents

- [Overview](#overview)
- [Installation](#installation)
- [Basic usage](#basic-usage)
- [Configuration Options](#configuration-options)
- [JavaScript API](#javascript-api)
- [Common Patterns](#common-patterns)
- [License](#license)

## Overview

The Textarea Autoheight component automatically adjusts the height of a textarea element based on its content. As users type, the textarea expands or contracts to fit the text, eliminating the need for scrollbars.

**Key Features:**
- Automatic height adjustment based on content
- Smooth resizing as user types
- Configurable default height
- Programmatic control via JavaScript API
- No scrollbars needed

## Installation

To get started, install Textarea Autoheight plugin via npm, else you can skip this step if you are already using Preline UI as a package.

```bash
npm i @preline/textarea-auto-height
```

### CSS

[`@import`](https://tailwindcss.com/docs/functions-and-directives#import-directive) the plugin's CSS file into your Tailwind CSS file.

```css
@import "tailwindcss";

/* @preline/textarea-auto-height */
@import "./node_modules/@preline/textarea-auto-height/theme.css";
```

### JavaScript

Include the JavaScript that powers the interactive elements near the end of your `</body>` tag:

```html
<script src="./node_modules/@preline/textarea-auto-height/index.js"></script>
```

### Manual Initialization

Use the `non-auto` entry if you need manual initialization. In this mode, automatic initialization on page load is not included, so the component should be initialized explicitly.

```html
<script type="module">
  import HSTextareaAutoHeight from "@preline/textarea-auto-height/non-auto.mjs";

  new HSTextareaAutoHeight(document.querySelector("#textarea"));
</script>
```

### Via Bundler

When using a bundler (Vite, webpack, etc.), import the plugin directly as an ES module.

`@preline/textarea-auto-height` is the auto-init entry: it scans the DOM and initializes matching elements automatically.

```js
import "@preline/textarea-auto-height";
```

`@preline/textarea-auto-height/non-auto` is the manual entry: use it when you want explicit control over when initialization happens, either via `autoInit()` or by creating a specific instance yourself.

```js
import HSTextareaAutoHeight from "@preline/textarea-auto-height/non-auto";

HSTextareaAutoHeight.autoInit();

// Or initialize a specific element manually
const el = document.querySelector("#textarea");
if (el) new HSTextareaAutoHeight(el);
```

### TypeScript

This package ships with TypeScript type definitions. No additional `@types/` package is needed.

## Basic usage

The following example demonstrates the minimal HTML structure required for a textarea autoheight component. This is a base template without custom styling - you can apply your own CSS classes and styles as needed. The textarea automatically adjusts its height as content is entered.

```html
<textarea data-hs-textarea-auto-height></textarea>
```

**Structure Requirements:**
- `data-hs-textarea-auto-height`: Required on the textarea element
- Standard `<textarea>` element

**Initial State:**
- Textarea starts at default height (or configured `defaultHeight`)
- Height adjusts automatically as content is entered or removed

## Configuration Options

### Data Options

Data options are specified in the `data-hs-textarea-auto-height` attribute.

| Attribute | Target Element | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `data-hs-textarea-auto-height` | Textarea element | - | - | If this attribute is added to the textarea, then automatic height calculation according to the content is enabled. Should be added to the textarea itself. |
| `:defaultHeight` | Inside `data-hs-textarea-auto-height` | number | `0` | Sets the default height (when no text is entered). When set to `0`, the textarea uses its natural height. |

**Example:**
```html
<textarea data-hs-textarea-auto-height='{
  "defaultHeight": 50
}'></textarea>
```

## JavaScript API

The `HSTextareaAutoHeight` object is available in the global `window` object after the plugin is loaded.

### Instance Methods

These methods are called on a textarea autoheight instance.

| Method | Parameters | Return Type | Description |
| --- | --- | --- | --- |
| `destroy()` | None | `void` | Destroys the textarea autoheight instance, removes all generated markup, classes, and event listeners. Use when removing textarea autoheight from DOM. |

### Static Methods

These methods are called directly on the `HSTextareaAutoHeight` class.

| Method | Parameters | Return Type | Description |
| --- | --- | --- | --- |
| `HSTextareaAutoHeight.getInstance(target, isInstance)` | `target`: `HTMLTextAreaElement \| string` (CSS selector)<br>`isInstance`: `boolean` (optional) | `HSTextareaAutoHeight \| { id: string \| number, element: HSTextareaAutoHeight } \| null` | Returns the textarea autoheight instance associated with the target. If `isInstance` is `true`, returns collection item object `{ id, element }` where `element` is the `HSTextareaAutoHeight` instance. If `isInstance` is `false` or omitted, returns the `HSTextareaAutoHeight` instance directly. Returns `null` if textarea autoheight instance is not found. |

### Usage Examples

**Example 1: Destroying textarea autoheight instance**
```javascript
const instance = HSTextareaAutoHeight.getInstance('#hs-textarea-autoheight', true);

if (instance) {
  const { element } = instance;
  const destroyBtn = document.querySelector('#hs-destroy-btn');

  destroyBtn.addEventListener('click', () => {
    element.destroy();
  });
}
```

**Example 2: Getting instance and accessing properties**
```javascript
// Get the textarea autoheight instance
const instance = HSTextareaAutoHeight.getInstance('#hs-textarea-autoheight', true);

if (instance) {
  const { element } = instance;

  // Access instance properties
  console.log('Default height:', element.defaultHeight);

  // Clean up when removing from DOM
  function removeTextareaAutoheight() {
    element.destroy();
  }
}
```

**Example 3: Destroying textarea autoheight instance**
```javascript
const instance = HSTextareaAutoHeight.getInstance('#hs-textarea-autoheight', true);

if (instance) {
  const { element } = instance;
  const removeBtn = document.querySelector('#hs-remove-btn');

  removeBtn.addEventListener('click', () => {
    // Clean up before removing from DOM
    element.destroy();
    // Now safe to remove the element
    document.querySelector('#hs-textarea-autoheight').remove();
  });
}
```

## Common Patterns

### Pattern 1: Custom Default Height

Set a custom default height for the textarea.

```html
<textarea data-hs-textarea-auto-height='{
  "defaultHeight": 100
}'></textarea>
```

### Pattern 2: Multiple Autoheight Textareas

Apply autoheight to multiple textareas.

```html
<textarea id="hs-comment-first" data-hs-textarea-auto-height></textarea>
<textarea id="hs-comment-second" data-hs-textarea-auto-height></textarea>
```

## License

Copyright (c) 2026 Preline Labs.

Licensed under the [MIT License](https://opensource.org/licenses/MIT).