0
# HTML Beautification
1
2
HTML code formatting with comprehensive support for various HTML elements, attributes, and embedded JavaScript/CSS. Includes advanced template language support and highly configurable element handling for modern web development workflows.
3
4
## Core Imports
5
6
```javascript
7
// Import HTML beautifier
8
const { html_beautify } = require('js-beautify');
9
const beautify = require('js-beautify');
10
11
// Or use the short alias
12
const { html } = require('js-beautify');
13
```
14
15
ESM:
16
```javascript
17
import beautify from 'js-beautify';
18
// Use beautify.html() for HTML beautification
19
```
20
21
## Capabilities
22
23
### HTML Beautify Function
24
25
Beautifies HTML source code with extensive control over element formatting, attribute wrapping, and embedded content handling.
26
27
```javascript { .api }
28
/**
29
* Beautify HTML source code with optional JS/CSS beautification
30
* @param {string} html_source - HTML code to beautify
31
* @param {Object} options - Formatting options (optional)
32
* @param {boolean} [options.indent_inner_html=false] - Indent <head> and <body> sections
33
* @param {boolean} [options.indent_body_inner_html=true] - Indent content inside <body>
34
* @param {boolean} [options.indent_head_inner_html=true] - Indent content inside <head>
35
* @param {boolean} [options.indent_handlebars=true] - Indent Handlebars templates
36
* @param {string} [options.wrap_attributes='auto'] - Attribute wrapping strategy: 'auto', 'force', 'force-aligned', 'force-expand-multiline', 'aligned-multiple', 'preserve', 'preserve-aligned'
37
* @param {number} [options.wrap_attributes_min_attrs=2] - Minimum number of attributes to trigger wrapping
38
* @param {number} [options.wrap_attributes_indent_size] - Indent size for wrapped attributes (defaults to indent_size)
39
* @param {string[]} [options.extra_liners] - List of tags that should have an extra newline before them
40
* @param {string[]} [options.inline] - List of tags to be considered inline tags
41
* @param {boolean} [options.inline_custom_elements=true] - Treat custom elements as inline
42
* @param {string[]} [options.void_elements] - List of void HTML elements
43
* @param {string[]} [options.unformatted] - List of tags that should not be reformatted
44
* @param {string[]} [options.content_unformatted] - List of tags whose content should not be reformatted
45
* @param {string} [options.unformatted_content_delimiter] - Keep text content together between this string delimiter
46
* @param {string} [options.indent_scripts='normal'] - Script tag indentation mode: 'normal', 'keep', 'separate'
47
* @param {Function} js_beautify - Custom JavaScript beautifier function (optional)
48
* @param {Function} css_beautify - Custom CSS beautifier function (optional)
49
* @returns {string} Beautified HTML code
50
*/
51
function html_beautify(html_source, options, js_beautify, css_beautify);
52
53
/**
54
* Get default options for HTML beautifier
55
* @returns {Object} Default options object with all HTML-specific options
56
*/
57
html_beautify.defaultOptions();
58
```
59
60
**Usage Examples:**
61
62
```javascript
63
const beautify = require('js-beautify');
64
65
// Basic HTML beautification
66
const uglyHTML = '<div><p>Hello</p><span>World</span></div>';
67
const beautiful = beautify.html(uglyHTML, { indent_size: 2 });
68
// Result:
69
// <div>
70
// <p>Hello</p>
71
// <span>World</span>
72
// </div>
73
74
// Attribute wrapping
75
const longAttributes = '<input type="text" class="form-control" placeholder="Enter your name" required>';
76
const wrapped = beautify.html(longAttributes, {
77
wrap_attributes: 'force',
78
wrap_attributes_min_attrs: 2,
79
indent_size: 2
80
});
81
// Result:
82
// <input
83
// type="text"
84
// class="form-control"
85
// placeholder="Enter your name"
86
// required>
87
88
// With embedded JS/CSS beautification
89
const embedded = '<script>function test(){return true;}</script><style>body{margin:0;}</style>';
90
const formatted = beautify.html(embedded, { indent_size: 2 });
91
// Automatically beautifies embedded JavaScript and CSS
92
```
93
94
### Default Options
95
96
Returns the default configuration options for HTML beautification.
97
98
```javascript { .api }
99
/**
100
* Get default options for HTML beautifier
101
* @returns {Object} Default options object with all HTML-specific options
102
*/
103
html_beautify.defaultOptions();
104
```
105
106
## Attribute Wrapping Modes
107
108
### Auto (Default)
109
Wraps attributes intelligently based on line length and attribute count.
110
111
### Force
112
Forces attributes to be wrapped when minimum attribute count is reached:
113
```html
114
<input
115
type="text"
116
class="form-control"
117
required>
118
```
119
120
### Force-Aligned
121
Forces wrapping with aligned attributes:
122
```html
123
<input type="text"
124
class="form-control"
125
required>
126
```
127
128
### Force-Expand-Multiline
129
Expands multiline attributes with each on its own line:
130
```html
131
<input
132
type="text"
133
class="form-control large-input"
134
placeholder="Enter your full name here"
135
required>
136
```
137
138
### Aligned-Multiple
139
Aligns multiple attributes per line:
140
```html
141
<input type="text" class="form-control"
142
placeholder="Enter name" required>
143
```
144
145
### Preserve / Preserve-Aligned
146
Preserves existing attribute formatting.
147
148
## Element Classification
149
150
### Inline Elements
151
Elements treated as inline (default includes standard HTML inline elements):
152
```javascript
153
// Default inline elements include:
154
['a', 'abbr', 'area', 'audio', 'b', 'bdi', 'bdo', 'br', 'button', 'canvas', 'cite',
155
'code', 'data', 'datalist', 'del', 'dfn', 'em', 'embed', 'i', 'iframe', 'img',
156
'input', 'ins', 'kbd', 'keygen', 'label', 'map', 'mark', 'math', 'meter', 'noscript',
157
'object', 'output', 'progress', 'q', 'ruby', 's', 'samp', 'select', 'small',
158
'span', 'strong', 'sub', 'sup', 'svg', 'template', 'textarea', 'time', 'u', 'var',
159
'video', 'wbr', 'text']
160
```
161
162
### Void Elements
163
Self-closing elements that don't have closing tags:
164
```javascript
165
// Default void elements include:
166
['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'keygen',
167
'link', 'menuitem', 'meta', 'param', 'source', 'track', 'wbr',
168
'!doctype', '?xml', 'basefont', 'isindex']
169
```
170
171
### Extra Liners
172
Elements that get extra newlines before them:
173
```javascript
174
// Default extra liners:
175
['head', 'body', '/html']
176
```
177
178
## Content Formatting Control
179
180
### Unformatted Elements
181
Elements whose tags should not be reformatted (empty by default).
182
183
### Content Unformatted
184
Elements whose content should not be reformatted:
185
```javascript
186
// Default content unformatted:
187
['pre', 'textarea']
188
```
189
190
**Example:**
191
```html
192
<pre>
193
This spacing
194
will be preserved
195
</pre>
196
```
197
198
### Unformatted Content Delimiter
199
Custom delimiter to preserve content formatting:
200
```javascript
201
const html = '<div>{{! This content will be preserved }}</div>';
202
const formatted = beautify.html(html, {
203
unformatted_content_delimiter: '{{!',
204
indent_size: 2
205
});
206
```
207
208
## Script and Style Handling
209
210
### Script Indentation Modes
211
212
#### Normal (Default)
213
Scripts are indented normally with the HTML:
214
```html
215
<script>
216
function test() {
217
return true;
218
}
219
</script>
220
```
221
222
#### Keep
223
Preserves original script indentation:
224
```html
225
<script>
226
function test() {
227
return true;
228
}
229
</script>
230
```
231
232
#### Separate
233
Scripts are unindented and separated:
234
```html
235
<script>
236
function test() {
237
return true;
238
}
239
</script>
240
```
241
242
## Template Language Support
243
244
### Supported Template Languages
245
The `templating` option supports:
246
- `auto` - Automatically detect (default for HTML)
247
- `none` - No template support
248
- `angular` - Angular templates
249
- `django` - Django templates
250
- `erb` - ERB templates (Ruby)
251
- `handlebars` - Handlebars templates
252
- `php` - PHP templates
253
- `smarty` - Smarty templates
254
255
**Example with Handlebars:**
256
```html
257
<div class="{{className}}">
258
{{#if showContent}}
259
<p>{{content}}</p>
260
{{/if}}
261
</div>
262
```
263
264
### Custom Elements Support
265
When `inline_custom_elements` is enabled (default), custom elements are treated as inline:
266
```html
267
<my-component>
268
<my-child-component></my-child-component>
269
</my-component>
270
```
271
272
## Advanced Features
273
274
### Embedded Content Beautification
275
HTML beautifier automatically beautifies embedded JavaScript and CSS:
276
```html
277
<!-- Input -->
278
<script>function test(){return 1+2;}</script>
279
<style>body{margin:0;padding:0;}</style>
280
281
<!-- Output -->
282
<script>
283
function test() {
284
return 1 + 2;
285
}
286
</script>
287
<style>
288
body {
289
margin: 0;
290
padding: 0;
291
}
292
</style>
293
```
294
295
### Directive Support
296
Supports beautify directives for fine-grained control:
297
```html
298
<!-- beautify ignore:start -->
299
<div>This content will not be formatted</div>
300
<!-- beautify ignore:end -->
301
302
<!-- beautify preserve:start -->
303
<div>
304
This content will be parsed but formatting preserved
305
</div>
306
<!-- beautify preserve:end -->
307
```