eslint/docs/src/rules/key-spacing.md

   1 ---
   2 title: key-spacing
   3 layout: doc
   4 rule_type: layout
   5 ---
   6
   7
   8
   9 This rule enforces spacing around the colon in object literal properties. It can verify each property individually, or it can ensure horizontal alignment of adjacent properties in an object literal.
  10
  11 ## Rule Details
  12
  13 This rule enforces consistent spacing between keys and values in object literal properties. In the case of long lines, it is acceptable to add a new line wherever whitespace is allowed.
  14
  15 ## Options
  16
  17 This rule has an object option:
  18
  19 * `"beforeColon": false (default) | true`
  20     * `false`: disallows spaces between the key and the colon in object literals.
  21     * `true`: requires at least one space between the key and the colon in object literals.
  22 * `"afterColon": true (default) | false`
  23     * `true`: requires at least one space between the colon and the value in object literals.
  24     * `false`: disallows spaces between the colon and the value in object literals.
  25 * `"mode": "strict" (default) | "minimum"`
  26     * `"strict"`: enforces exactly one space before or after colons in object literals.
  27     * `"minimum"`: enforces one or more spaces before or after colons in object literals.
  28 * `"align": "value" | "colon"`
  29     * `"value"`: enforces horizontal alignment of values in object literals.
  30     * `"colon"` enforces horizontal alignment of both colons and values in object literals.
  31 * `"align"` with an object value allows for fine-grained spacing when values are being aligned in object literals.
  32 * `"singleLine"` specifies a spacing style for single-line object literals.
  33 * `"multiLine"` specifies a spacing style for multi-line object literals.
  34
  35 Please note that you can either use the top-level options or the grouped options (`singleLine` and `multiLine`) but not both.
  36
  37 ### beforeColon
  38
  39 Examples of **incorrect** code for this rule with the default `{ "beforeColon": false }` option:
  40
  41 ::: incorrect
  42
  43 ```js
  44 /*eslint key-spacing: ["error", { "beforeColon": false }]*/
  45
  46 var obj = { "foo" : 42 };
  47 ```
  48
  49 :::
  50
  51 Examples of **correct** code for this rule with the default `{ "beforeColon": false }` option:
  52
  53 ::: correct
  54
  55 ```js
  56 /*eslint key-spacing: ["error", { "beforeColon": false }]*/
  57
  58 var obj = { "foo": 42 };
  59 ```
  60
  61 :::
  62
  63 Examples of **incorrect** code for this rule with the `{ "beforeColon": true }` option:
  64
  65 ::: incorrect
  66
  67 ```js
  68 /*eslint key-spacing: ["error", { "beforeColon": true }]*/
  69
  70 var obj = { "foo": 42 };
  71 ```
  72
  73 :::
  74
  75 Examples of **correct** code for this rule with the `{ "beforeColon": true }` option:
  76
  77 ::: correct
  78
  79 ```js
  80 /*eslint key-spacing: ["error", { "beforeColon": true }]*/
  81
  82 var obj = { "foo" : 42 };
  83 ```
  84
  85 :::
  86
  87 ### afterColon
  88
  89 Examples of **incorrect** code for this rule with the default `{ "afterColon": true }` option:
  90
  91 ::: incorrect
  92
  93 ```js
  94 /*eslint key-spacing: ["error", { "afterColon": true }]*/
  95
  96 var obj = { "foo":42 };
  97 ```
  98
  99 :::
 100
 101 Examples of **correct** code for this rule with the default `{ "afterColon": true }` option:
 102
 103 ::: correct
 104
 105 ```js
 106 /*eslint key-spacing: ["error", { "afterColon": true }]*/
 107
 108 var obj = { "foo": 42 };
 109 ```
 110
 111 :::
 112
 113 Examples of **incorrect** code for this rule with the `{ "afterColon": false }` option:
 114
 115 ::: incorrect
 116
 117 ```js
 118 /*eslint key-spacing: ["error", { "afterColon": false }]*/
 119
 120 var obj = { "foo": 42 };
 121 ```
 122
 123 :::
 124
 125 Examples of **correct** code for this rule with the `{ "afterColon": false }` option:
 126
 127 ::: correct
 128
 129 ```js
 130 /*eslint key-spacing: ["error", { "afterColon": false }]*/
 131
 132 var obj = { "foo":42 };
 133 ```
 134
 135 :::
 136
 137 ### mode
 138
 139 Examples of **incorrect** code for this rule with the default `{ "mode": "strict" }` option:
 140
 141 ::: incorrect
 142
 143 ```js
 144 /*eslint key-spacing: ["error", { "mode": "strict" }]*/
 145
 146 call({
 147     foobar: 42,
 148     bat:    2 * 2
 149 });
 150 ```
 151
 152 :::
 153
 154 Examples of **correct** code for this rule with the default `{ "mode": "strict" }` option:
 155
 156 ::: correct
 157
 158 ```js
 159 /*eslint key-spacing: ["error", { "mode": "strict" }]*/
 160
 161 call({
 162     foobar: 42,
 163     bat: 2 * 2
 164 });
 165 ```
 166
 167 :::
 168
 169 Examples of **correct** code for this rule with the `{ "mode": "minimum" }` option:
 170
 171 ::: correct
 172
 173 ```js
 174 /*eslint key-spacing: ["error", { "mode": "minimum" }]*/
 175
 176 call({
 177     foobar: 42,
 178     bat:    2 * 2
 179 });
 180 ```
 181
 182 :::
 183
 184 ### align
 185
 186 Examples of **incorrect** code for this rule with the `{ "align": "value" }` option:
 187
 188 ::: incorrect
 189
 190 ```js
 191 /*eslint key-spacing: ["error", { "align": "value" }]*/
 192
 193 var obj = {
 194     a: value,
 195     bcde:  42,
 196     fg :   foo()
 197 };
 198 ```
 199
 200 :::
 201
 202 Examples of **correct** code for this rule with the `{ "align": "value" }` option:
 203
 204 ::: correct
 205
 206 ```js
 207 /*eslint key-spacing: ["error", { "align": "value" }]*/
 208
 209 var obj = {
 210     a:    value,
 211     bcde: 42,
 212
 213     fg: foo(),
 214     h:  function() {
 215         return this.a;
 216     },
 217     ijkl: 'Non-consecutive lines form a new group'
 218 };
 219
 220 var obj = { a: "foo", longPropertyName: "bar" };
 221 ```
 222
 223 :::
 224
 225 Examples of **incorrect** code for this rule with the `{ "align": "colon" }` option:
 226
 227 ::: incorrect
 228
 229 ```js
 230 /*eslint key-spacing: ["error", { "align": "colon" }]*/
 231
 232 call({
 233     foobar: 42,
 234     bat:    2 * 2
 235 });
 236 ```
 237
 238 :::
 239
 240 Examples of **correct** code for this rule with the `{ "align": "colon" }` option:
 241
 242 ::: correct
 243
 244 ```js
 245 /*eslint key-spacing: ["error", { "align": "colon" }]*/
 246
 247 call({
 248     foobar: 42,
 249     bat   : 2 * 2
 250 });
 251 ```
 252
 253 :::
 254
 255 ### align
 256
 257 The `align` option can take additional configuration through the `beforeColon`, `afterColon`, `mode`, and `on` options.
 258
 259 If `align` is defined as an object, but not all of the parameters are provided, undefined parameters will default to the following:
 260
 261 ```js
 262 // Defaults
 263 align: {
 264     "beforeColon": false,
 265     "afterColon": true,
 266     "on": "colon",
 267     "mode": "strict"
 268 }
 269 ```
 270
 271 Examples of **correct** code for this rule with sample `{ "align": { } }` options:
 272
 273 ::: correct
 274
 275 ```js
 276 /*eslint key-spacing: ["error", {
 277     "align": {
 278         "beforeColon": true,
 279         "afterColon": true,
 280         "on": "colon"
 281     }
 282 }]*/
 283
 284 var obj = {
 285     "one"   : 1,
 286     "seven" : 7
 287 }
 288 ```
 289
 290 :::
 291
 292 ::: correct
 293
 294 ```js
 295 /*eslint key-spacing: ["error", {
 296     "align": {
 297         "beforeColon": false,
 298         "afterColon": false,
 299         "on": "value"
 300     }
 301 }]*/
 302
 303 var obj = {
 304     "one":  1,
 305     "seven":7
 306 }
 307 ```
 308
 309 :::
 310
 311 ### align and multiLine
 312
 313 The `multiLine` and `align` options can differ, which allows for fine-tuned control over the `key-spacing` of your files.  `align` will **not** inherit from `multiLine` if `align` is configured as an object.
 314
 315 `multiLine` is used any time  an object literal spans multiple lines.  The `align` configuration is used when there is a group of properties in the same object. For example:
 316
 317 ```javascript
 318 var myObj = {
 319   key1: 1, // uses multiLine
 320
 321   key2: 2, // uses align (when defined)
 322   key3: 3, // uses align (when defined)
 323
 324   key4: 4 // uses multiLine
 325 }
 326
 327 ```
 328
 329 Examples of **incorrect** code for this rule with sample `{ "align": { }, "multiLine": { } }` options:
 330
 331 ::: incorrect
 332
 333 ```js
 334 /*eslint key-spacing: ["error", {
 335     "multiLine": {
 336         "beforeColon": false,
 337         "afterColon":true
 338     },
 339     "align": {
 340         "beforeColon": true,
 341         "afterColon": true,
 342         "on": "colon"
 343     }
 344 }]*/
 345
 346 var obj = {
 347     "myObjectFunction": function() {
 348         // Do something
 349     },
 350     "one"             : 1,
 351     "seven"           : 7
 352 }
 353 ```
 354
 355 :::
 356
 357 Examples of **correct** code for this rule with sample `{ "align": { }, "multiLine": { } }` options:
 358
 359 ::: correct
 360
 361 ```js
 362 /*eslint key-spacing: ["error", {
 363     "multiLine": {
 364         "beforeColon": false,
 365         "afterColon": true
 366
 367     },
 368     "align": {
 369         "beforeColon": true,
 370         "afterColon": true,
 371         "on": "colon"
 372     }
 373 }]*/
 374
 375 var obj = {
 376     "myObjectFunction": function() {
 377         // Do something
 378         //
 379     }, // These are two separate groups, so no alignment between `myObjectFunction` and `one`
 380     "one"   : 1,
 381     "seven" : 7 // `one` and `seven` are in their own group, and therefore aligned
 382 }
 383 ```
 384
 385 :::
 386
 387 ### singleLine and multiLine
 388
 389 Examples of **correct** code for this rule with sample `{ "singleLine": { }, "multiLine": { } }` options:
 390
 391 ::: correct
 392
 393 ```js
 394 /*eslint "key-spacing": [2, {
 395     "singleLine": {
 396         "beforeColon": false,
 397         "afterColon": true
 398     },
 399     "multiLine": {
 400         "beforeColon": true,
 401         "afterColon": true,
 402         "align": "colon"
 403     }
 404 }]*/
 405 var obj = { one: 1, "two": 2, three: 3 };
 406 var obj2 = {
 407     "two" : 2,
 408     three : 3
 409 };
 410 ```
 411
 412 :::
 413
 414 ## When Not To Use It
 415
 416 If you have another convention for property spacing that might not be consistent with the available options, or if you want to permit multiple styles concurrently you can safely disable this rule.