0
# Tailwind CSS Forms
1

2
A Tailwind CSS plugin that provides comprehensive form element styling and normalization. It offers two strategies for applying styles: 'base' for global form element styling and 'class' for explicit utility classes, with support for all standard HTML form input types.
3

4
## Package Information
5

6
- **Package Name**: @tailwindcss/forms
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install -D @tailwindcss/forms`
10

11
## Core Imports
12

13
```javascript
14
const forms = require('@tailwindcss/forms');
15
```
16

17
For ES modules:
18

19
```javascript
20
import forms from '@tailwindcss/forms';
21
```
22

23
## Basic Usage
24

25
Add the plugin to your `tailwind.config.js` file:
26

27
```javascript
28
// tailwind.config.js
29
module.exports = {
30
  theme: {
31
    // ...
32
  },
33
  plugins: [
34
    require('@tailwindcss/forms'),
35
    // ...
36
  ],
37
}
38
```
39

40
With configuration options:
41

42
```javascript
43
// tailwind.config.js
44
module.exports = {
45
  plugins: [
46
    require('@tailwindcss/forms')({
47
      strategy: 'base', // only generate global styles
48
    }),
49
    // or
50
    require('@tailwindcss/forms')({
51
      strategy: 'class', // only generate classes
52
    }),
53
  ],
54
}
55
```
56

57
## Architecture
58

59
The @tailwindcss/forms plugin is built around the following design:
60

61
- **Strategy System**: Supports both global base styles and utility classes via the `strategy` option
62
- **Form Element Normalization**: Provides consistent cross-browser styling for all form input types
63
- **Custom Icon Integration**: Uses SVG data URIs for custom checkbox, radio, and select dropdown icons
64
- **Theme Integration**: Seamlessly integrates with Tailwind's color and spacing systems
65
- **Focus State Management**: Automatic focus ring styling using Tailwind's ring utilities
66
- **WebKit Compatibility**: Special handling for Safari and Chrome date/time input quirks
67

68
## Capabilities
69

70
### Plugin Configuration
71

72
Main plugin function that configures form styling behavior.
73

74
```javascript { .api }
75
/**
76
 * Tailwind CSS forms plugin created using plugin.withOptions()
77
 * @param options - Configuration options for the plugin
78
 * @returns Tailwind CSS plugin instance
79
 */
80
const forms = plugin.withOptions(function (options = { strategy: undefined }) {
81
  // Plugin implementation
82
});
83

84
interface FormPluginOptions {
85
  /** Strategy for applying form styles */
86
  strategy?: 'base' | 'class';
87
}
88
```
89

90
**Configuration Details:**
91

92
- `strategy: 'base'` - Applies styles globally to form elements (default when combined with 'class')
93
- `strategy: 'class'` - Generates utility classes only (form-input, form-select, etc.)
94
- `strategy: undefined` - Applies both base styles and generates utility classes (default behavior)
95

96
### Form Element Styling
97

98
The plugin provides styling for all standard HTML form input types through two approaches:
99

100
#### Base Strategy Selectors
101

102
When using base strategy, the following selectors receive automatic styling:
103

104
```css { .api }
105
/* Text input types */
106
[type='text']
107
input:where(:not([type]))  /* inputs without type attribute */
108
[type='email']
109
[type='url']
110
[type='password']
111
[type='number']
112
[type='date']
113
[type='datetime-local']
114
[type='month']
115
[type='search']
116
[type='tel']
117
[type='time']
118
[type='week']
119

120
/* Other form elements */
121
textarea
122
select
123
[multiple]  /* multi-select elements */
124
[type='checkbox']
125
[type='radio']
126
[type='file']  /* minimal reset only */
127
```
128

129
#### Utility Classes (Class Strategy)
130

131
When using class strategy, the following utility classes are generated:
132

133
```css { .api }
134
.form-input        /* For text, email, password, number, date, etc. inputs */
135
.form-textarea     /* For textarea elements */
136
.form-select       /* For single select elements */
137
.form-multiselect  /* For multiple select elements */
138
.form-checkbox     /* For checkbox inputs */
139
.form-radio        /* For radio inputs */
140
```
141

142
### Form Element Features
143

144
#### Text Input Styling
145

146
All text-type inputs receive consistent styling with:
147

148
- Normalized appearance and border styling
149
- Consistent padding and typography
150
- Automatic focus ring states using Tailwind's ring utilities
151
- Placeholder text styling
152
- WebKit-specific fixes for date/time inputs
153

154
#### Select Element Styling
155

156
Select elements receive:
157

158
- Custom dropdown arrow using SVG data URI
159
- Consistent styling with other inputs
160
- Automatic removal of custom arrow for multi-select elements
161
- Theme-aware arrow color that respects Tailwind color configuration
162

163
#### Checkbox and Radio Styling
164

165
Checkbox and radio inputs feature:
166

167
- Custom SVG icons for checked states
168
- Consistent sizing and positioning
169
- Indeterminate state support for checkboxes
170
- Focus ring styling
171
- Color theming support
172
- High contrast mode compatibility
173

174
#### File Input Handling
175

176
File inputs receive minimal reset styling to preserve browser functionality while maintaining consistency.
177

178
## Supported Form Input Types
179

180
The plugin provides comprehensive support for all HTML form input types:
181

182
### Text Input Types
183
- `type="text"` - Standard text input
184
- `type="email"` - Email address input
185
- `type="url"` - URL input
186
- `type="password"` - Password input
187
- `type="number"` - Numeric input
188
- `type="search"` - Search input
189
- `type="tel"` - Telephone number input
190

191
### Date and Time Input Types
192
- `type="date"` - Date picker
193
- `type="datetime-local"` - Local date and time
194
- `type="month"` - Month picker
195
- `type="time"` - Time picker
196
- `type="week"` - Week picker
197

198
### Other Input Types
199
- `type="checkbox"` - Checkbox input
200
- `type="radio"` - Radio button input
201
- `type="file"` - File upload input
202
- `textarea` - Multi-line text input
203
- `select` - Single selection dropdown
204
- `select[multiple]` - Multi-selection list
205

206
## Usage Examples
207

208
### Basic Form Styling
209

210
```html
211
<!-- Using base strategy (automatic styling) -->
212
<form>
213
  <input type="text" placeholder="Full name" />
214
  <input type="email" placeholder="Email address" />
215
  <select>
216
    <option>Choose option</option>
217
    <option>Option 1</option>
218
    <option>Option 2</option>
219
  </select>
220
  <textarea placeholder="Message"></textarea>
221
  <input type="checkbox" id="agree" />
222
  <label for="agree">I agree to terms</label>
223
</form>
224
```
225

226
### Using Utility Classes
227

228
```html
229
<!-- Using class strategy (explicit classes) -->
230
<form>
231
  <input type="text" class="form-input rounded-lg" placeholder="Full name" />
232
  <input type="email" class="form-input rounded-lg" placeholder="Email" />
233
  <select class="form-select rounded-lg">
234
    <option>Choose option</option>
235
  </select>
236
  <textarea class="form-textarea rounded-lg" placeholder="Message"></textarea>
237
  <input type="checkbox" class="form-checkbox text-blue-600" id="agree" />
238
</form>
239
```
240

241
### Custom Styling with Tailwind Utilities
242

243
```html
244
<!-- Combining with Tailwind utilities -->
245
<input type="email" class="form-input px-4 py-3 rounded-full border-2 border-blue-300 focus:border-blue-500" />
246
<select class="form-select bg-gray-50 text-lg rounded-xl">
247
  <option>Large rounded select</option>
248
</select>
249
<input type="checkbox" class="form-checkbox h-6 w-6 text-green-600 rounded-lg" />
250
```
251

252
## Dependencies
253

254
The plugin has minimal dependencies:
255

256
```javascript { .api }
257
// External dependency for SVG data URI conversion
258
const svgToDataUri = require('mini-svg-data-uri');
259

260
// Tailwind CSS plugin utilities
261
const plugin = require('tailwindcss/plugin');
262
const defaultTheme = require('tailwindcss/defaultTheme');
263
const colors = require('tailwindcss/colors');
264

265
// Destructured defaults from Tailwind's default theme
266
const [baseFontSize, { lineHeight: baseLineHeight }] = defaultTheme.fontSize.base;
267
const { spacing, borderWidth, borderRadius } = defaultTheme;
268

269
/**
270
 * Utility function to resolve color values with alpha-value placeholder support
271
 * @param color - Color value that may contain '<alpha-value>' placeholder
272
 * @param opacityVariableName - CSS custom property name for opacity
273
 * @returns Resolved color value with proper opacity variable
274
 */
275
function resolveColor(color, opacityVariableName) {
276
  return color.replace('<alpha-value>', `var(${opacityVariableName}, 1)`);
277
}
278

279
/**
280
 * Internal utility to resolve chevron colors for select dropdown arrows
281
 * @param color - Theme color path
282
 * @param fallback - Fallback color value
283
 * @returns Resolved color without CSS variables
284
 */
285
function resolveChevronColor(color, fallback) {
286
  let resolved = theme(color);
287
  
288
  if (!resolved || resolved.includes('var(')) {
289
    return fallback;
290
  }
291
  
292
  return resolved.replace('<alpha-value>', '1');
293
}
294
```
295

296
## Browser Compatibility
297

298
The plugin includes specific handling for browser compatibility issues:
299

300
- **WebKit Date/Time Inputs**: Special fixes for Safari and Chrome date/time input rendering
301
- **High Contrast Mode**: Automatic appearance fallbacks for forced-colors media queries
302
- **Print Styles**: Color adjustment settings for proper printing
303
- **Cross-browser Normalization**: Consistent appearance across all modern browsers
304

305
## TypeScript Support
306

307
The plugin includes TypeScript definitions:
308

309
```typescript { .api }
310
declare const forms: {
311
  (options?: Partial<{ strategy: 'base' | 'class' }>): {
312
    handler: (tailwindApi: { addBase: Function; addComponents: Function; theme: Function }) => void;
313
  };
314
  __isOptionsFunction: true;
315
};
316

317
export = forms;
318
```