Tailwind CSS Forms

https://github.com/tailwindlabs/tailwindcss-forms
Admin
A plugin for Tailwind CSS that provides a basic reset for form styles, making form elements easy to...
Tokens:6,821
Snippets:69
Trust Score:9.3
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### HTML example for class-only strategy

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/api-reference/plugin.md

Shows how to apply form-* classes to elements when using the 'class' strategy. No global element styles are emitted.

```html
<input type="email" class="form-input rounded-full px-4 py-3" />
<select class="form-select rounded-full px-4 py-3">
  <!-- ... -->
</select>
<input type="checkbox" class="form-checkbox rounded text-pink-500" />
```

--------------------------------

### Install @tailwindcss/forms via npm

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/README.md

Use this command to install the plugin as a development dependency in your project.

```sh
npm install -D @tailwindcss/forms
```

--------------------------------

### Tailwind CSS v4 configuration with @plugin at-rule

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/configuration.md

Example main stylesheet for Tailwind CSS v4. Shows how to import Tailwind and use the `@plugin` at-rule to register the forms plugin, with and without options.

```css
/* app.css */
@import "tailwindcss";
@plugin "@tailwindcss/forms"; /* default: both strategies */

/* with options: */
@plugin "@tailwindcss/forms" {
  strategy: "base";
}
```

--------------------------------

### Tailwind CSS v3 configuration with @tailwindcss/forms

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/configuration.md

Example `tailwind.config.js` for Tailwind CSS v3. Shows how to register the plugin with default options (both strategies), or with `strategy: 'class'` or `strategy: 'base'`.

```javascript
// tailwind.config.js
module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('@tailwindcss/forms'), // default: both strategies
    // or:
    require('@tailwindcss/forms')({ strategy: 'class' }), // only classes
    // or:
    require('@tailwindcss/forms')({ strategy: 'base' }), // only global styles
  ],
}
```

--------------------------------

### Consuming the plugin with CommonJS import

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/types.md

Shows how to import the plugin and register it with or without options using the required CommonJS syntax.

```ts
import plugin = require('@tailwindcss/forms')

// bare registration
// plugins: [plugin]

// with options
const configured = plugin({ strategy: 'class' })
// configured.handler === (addBase, addComponents, theme) => void
```

--------------------------------

### JavaScript implementation of plugin()

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/api-reference/plugin.md

The exact JavaScript implementation from src/index.js (lines 12–25). Uses plugin.withOptions to return a handler that adds base and component styles based on the strategy option.

```js
const forms = plugin.withOptions(function (options = { strategy: undefined }) {
  return function ({ addBase, addComponents, theme }) {
    // ...
    const strategy = options.strategy === undefined ? ['base', 'class'] : [options.strategy]
    // ...
  }
})

module.exports = forms
```

--------------------------------

### Namespace member __isOptionsFunction

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/types.md

A type-level marker that distinguishes options-functions from plain handler plugins.

```ts
declare namespace plugin {
  const __isOptionsFunction: true
}
```

--------------------------------

### Apply form styles using explicit classes

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/README.md

Use the generated form-* classes to apply styles to elements, which is useful for non-form elements or specific styling needs.

```html
<input type="email" class="form-input rounded-full px-4 py-3" />

<select class="form-select rounded-full px-4 py-3">
  <!-- ... -->
</select>

<input type="checkbox" class="form-checkbox rounded text-pink-500" />
```

--------------------------------

### plugin(options?)

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/api-reference/plugin.md

The plugin function for @tailwindcss/forms. It can be called with an optional options object to configure the strategy (base or class). When registered without arguments, it uses default options with both base and class strategies.

```APIDOC
## plugin(options?)

### Description
Registers the @tailwindcss/forms plugin with Tailwind CSS. When called with no arguments, it uses default options (both base and class strategies). When called with an options object, it applies the specified strategy.

### Method
Function call (Tailwind plugin registration)

### Parameters
#### Options (optional)
- **strategy** (string) - Optional - The strategy to use: 'base' or 'class'. Defaults to both strategies when not specified.

### Usage
#### Bare registration (Tailwind v3 config)
```js
module.exports = {
  plugins: [
    require('@tailwindcss/forms')
  ]
}
```

#### Options invocation
```js
module.exports = {
  plugins: [
    require('@tailwindcss/forms')({ strategy: 'class' })
  ]
}
```

#### Tailwind v4 stylesheet
```css
@plugin "@tailwindcss/forms";
```

### Notes
- The plugin is built with Tailwind's `plugin.withOptions` factory.
- The function has `__isOptionsFunction = true` attached to support options invocation.
- Peer dependency: tailwindcss >=3.0.0 || >= 3.0.0-alpha.1 || >= 4.0.0-alpha.20 || >= 4.0.0-beta.1
```

--------------------------------

### Customize form elements with utilities

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/README.md

Apply standard Tailwind utility classes to form elements to override the default reset styles.

```html
<!-- You can actually customize padding on a select element now: -->
<select class="rounded-full px-4 py-3">
  <!-- ... -->
</select>

<!-- Or change a checkbox color using text color utilities: -->
<input type="checkbox" class="rounded text-pink-500" />
```

--------------------------------

### plugin(options?)

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/api-reference/plugin.md

The main plugin function that creates a Tailwind CSS plugin for form styling. It accepts an optional configuration object with a strategy field to control whether base styles, component classes, or both are generated.

```APIDOC
## plugin(options?)

### Description
Creates a Tailwind CSS plugin that generates form styles. The plugin can generate global base styles, form-* component classes, or both, depending on the strategy option.

### Signature
```ts
declare function plugin(options?: Partial<{ strategy: 'base' | 'class' }>): {
  handler: () => void
}
```

### Parameters
#### Options
- **options** (Partial<{ strategy: 'base' | 'class' }>) - Optional - Plugin configuration. When `options.strategy === undefined`, the plugin generates both global (`base`) styles and `form-*` component classes (`['base', 'class']`). If `strategy` is provided, only that strategy is generated (`[options.strategy]`).

### Return Value
- **{ handler: () => void }** - A Tailwind plugin descriptor consumed by Tailwind's plugin loader. `handler` is a function receiving the Tailwind helper context `{ addBase, addComponents, theme }`. At build time the handler calls `addBase` / `addComponents` with the selected rule set; it returns nothing (`undefined`).
```

--------------------------------

### Class-only strategy in Tailwind v4 and v3

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/api-reference/plugin.md

Configures the plugin to use the 'class' strategy, which disables global element styles and requires elements to opt in with form-* classes. Shows both Tailwind v4 CSS and v3 JavaScript configuration.

```css
/* app.css — Tailwind v4 */
@plugin "@tailwindcss/forms" {
  strategy: "class";
}
```

```javascript
// tailwind.config.js — Tailwind v3
module.exports = {
  plugins: [
    require('@tailwindcss/forms')({ strategy: 'class' }),
  ],
}
```

--------------------------------

### Base-only strategy in Tailwind v3

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/api-reference/plugin.md

Configures the plugin to use the 'base' strategy, which styles all supported form elements globally and does not generate form-* classes.

```javascript
// tailwind.config.js — Tailwind v3
module.exports = {
  plugins: [
    require('@tailwindcss/forms')({ strategy: 'base' }), // only global styles
  ],
}
```

--------------------------------

### TypeScript declaration of plugin()

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/api-reference/plugin.md

The exact TypeScript declaration from src/index.d.ts. Declares the plugin function with an optional options object and a namespace constant __isOptionsFunction.

```ts
declare function plugin(options?: Partial<{ strategy: 'base' | 'class' }>): {
  handler: () => void
}

declare namespace plugin {
  const __isOptionsFunction: true
}

export = plugin
```

--------------------------------

### Basic registration in Tailwind CSS v3 config

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/api-reference/plugin.md

Registers the @tailwindcss/forms plugin in a Tailwind CSS v3 configuration file. This generates global base resets and companion classes like .form-input and .form-select.

```javascript
// tailwind.config.js
module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require('@tailwindcss/forms'),
    // ...
  ],
}
```

--------------------------------

### Normalize strategy option in JavaScript

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/configuration.md

Runtime normalization of the `strategy` option, exactly as in `src/index.js` line 24. If `options.strategy` is `undefined`, it defaults to both `'base'` and `'class'`; otherwise, it uses the provided value.

```javascript
const strategy = options.strategy === undefined ? ['base', 'class'] : [options.strategy]
```

--------------------------------

### Configure strategy in Tailwind CSS v4

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/README.md

Limit the plugin to either base styles or class-based styles using the strategy option in your stylesheet.

```css
/* app.css */
@plugin "@tailwindcss/forms" {
  strategy: "base"; /* only generate global styles; or */
  strategy: "class"; /* only generate classes */
}
```

--------------------------------

### Configure strategy in Tailwind CSS v3

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/README.md

Limit the plugin to either base styles or class-based styles using the strategy option in your tailwind.config.js file.

```js
// tailwind.config.js
plugins: [
  require("@tailwindcss/forms")({
    strategy: 'base', // only generate global styles
    strategy: 'class', // only generate classes
  }),
],
```

--------------------------------

### Basic registration in Tailwind CSS v4 stylesheet

Source: https://github.com/tailwindlabs/tailwindcss-forms/blob/main/_autodocs/api-reference/plugin.md

Registers the @tailwindcss/forms plugin in a Tailwind CSS v4 stylesheet using the @plugin directive.

```css
/* app.css */
@import "tailwindcss";
@plugin "@tailwindcss/forms";
```
Tokens:
Raw