eslint/docs/rules/key-spacing.md

   1 # enforce consistent spacing between keys and values in object literal properties (key-spacing)
   2
   3 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.
   4
   5 ## Rule Details
   6
   7 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.
   8
   9 ## Options
  10
  11 This rule has an object option:
  12
  13 * `"beforeColon": false (default) | true`
  14     * `false`: disallows spaces between the key and the colon in object literals.
  15     * `true`: requires at least one space between the key and the colon in object literals.
  16 * `"afterColon": true (default) | false`
  17     * `true`: requires at least one space between the colon and the value in object literals.
  18     * `false`: disallows spaces between the colon and the value in object literals.
  19 * `"mode": "strict" (default) | "minimum"`
  20     * `"strict"`: enforces exactly one space before or after colons in object literals.
  21     * `"minimum"`: enforces one or more spaces before or after colons in object literals.
  22 * `"align": "value" | "colon"`
  23     * `"value"`: enforces horizontal alignment of values in object literals.
  24     * `"colon"` enforces horizontal alignment of both colons and values in object literals.
  25 * `"align"` with an object value allows for fine-grained spacing when values are being aligned in object literals.
  26 * `"singleLine"` specifies a spacing style for single-line object literals.
  27 * `"multiLine"` specifies a spacing style for multi-line object literals.
  28
  29 Please note that you can either use the top-level options or the grouped options (`singleLine` and `multiLine`) but not both.
  30
  31 ### beforeColon
  32
  33 Examples of **incorrect** code for this rule with the default `{ "beforeColon": false }` option:
  34
  35 ```js
  36 /*eslint key-spacing: ["error", { "beforeColon": false }]*/
  37
  38 var obj = { "foo" : 42 };
  39 ```
  40
  41 Examples of **correct** code for this rule with the default `{ "beforeColon": false }` option:
  42
  43 ```js
  44 /*eslint key-spacing: ["error", { "beforeColon": false }]*/
  45
  46 var obj = { "foo": 42 };
  47 ```
  48
  49 Examples of **incorrect** code for this rule with the `{ "beforeColon": true }` option:
  50
  51 ```js
  52 /*eslint key-spacing: ["error", { "beforeColon": true }]*/
  53
  54 var obj = { "foo": 42 };
  55 ```
  56
  57 Examples of **correct** code for this rule with the `{ "beforeColon": true }` option:
  58
  59 ```js
  60 /*eslint key-spacing: ["error", { "beforeColon": true }]*/
  61
  62 var obj = { "foo" : 42 };
  63 ```
  64
  65 ### afterColon
  66
  67 Examples of **incorrect** code for this rule with the default `{ "afterColon": true }` option:
  68
  69 ```js
  70 /*eslint key-spacing: ["error", { "afterColon": true }]*/
  71
  72 var obj = { "foo":42 };
  73 ```
  74
  75 Examples of **correct** code for this rule with the default `{ "afterColon": true }` option:
  76
  77 ```js
  78 /*eslint key-spacing: ["error", { "afterColon": true }]*/
  79
  80 var obj = { "foo": 42 };
  81 ```
  82
  83 Examples of **incorrect** code for this rule with the `{ "afterColon": false }` option:
  84
  85 ```js
  86 /*eslint key-spacing: ["error", { "afterColon": false }]*/
  87
  88 var obj = { "foo": 42 };
  89 ```
  90
  91 Examples of **correct** code for this rule with the `{ "afterColon": false }` option:
  92
  93 ```js
  94 /*eslint key-spacing: ["error", { "afterColon": false }]*/
  95
  96 var obj = { "foo":42 };
  97 ```
  98
  99 ### mode
 100
 101 Examples of **incorrect** code for this rule with the default `{ "mode": "strict" }` option:
 102
 103 ```js
 104 /*eslint key-spacing: ["error", { "mode": "strict" }]*/
 105
 106 call({
 107     foobar: 42,
 108     bat:    2 * 2
 109 });
 110 ```
 111
 112 Examples of **correct** code for this rule with the default `{ "mode": "strict" }` option:
 113
 114 ```js
 115 /*eslint key-spacing: ["error", { "mode": "strict" }]*/
 116
 117 call({
 118     foobar: 42,
 119     bat: 2 * 2
 120 });
 121 ```
 122
 123 Examples of **correct** code for this rule with the `{ "mode": "minimum" }` option:
 124
 125 ```js
 126 /*eslint key-spacing: ["error", { "mode": "minimum" }]*/
 127
 128 call({
 129     foobar: 42,
 130     bat:    2 * 2
 131 });
 132 ```
 133
 134 ### align
 135
 136 Examples of **incorrect** code for this rule with the `{ "align": "value" }` option:
 137
 138 ```js
 139 /*eslint key-spacing: ["error", { "align": "value" }]*/
 140
 141 var obj = {
 142     a: value,
 143     bcde:  42,
 144     fg :   foo()
 145 };
 146 ```
 147
 148 Examples of **correct** code for this rule with the `{ "align": "value" }` option:
 149
 150 ```js
 151 /*eslint key-spacing: ["error", { "align": "value" }]*/
 152
 153 var obj = {
 154     a:    value,
 155     bcde: 42,
 156
 157     fg: foo(),
 158     h:  function() {
 159         return this.a;
 160     },
 161     ijkl: 'Non-consecutive lines form a new group'
 162 };
 163
 164 var obj = { a: "foo", longPropertyName: "bar" };
 165 ```
 166
 167 Examples of **incorrect** code for this rule with the `{ "align": "colon" }` option:
 168
 169 ```js
 170 /*eslint key-spacing: ["error", { "align": "colon" }]*/
 171
 172 call({
 173     foobar: 42,
 174     bat:    2 * 2
 175 });
 176 ```
 177
 178 Examples of **correct** code for this rule with the `{ "align": "colon" }` option:
 179
 180 ```js
 181 /*eslint key-spacing: ["error", { "align": "colon" }]*/
 182
 183 call({
 184     foobar: 42,
 185     bat   : 2 * 2
 186 });
 187 ```
 188
 189 ### align
 190
 191 The `align` option can take additional configuration through the `beforeColon`, `afterColon`, `mode`, and `on` options.
 192
 193 If `align` is defined as an object, but not all of the parameters are provided, undefined parameters will default to the following:
 194
 195 ```js
 196 // Defaults
 197 align: {
 198     "beforeColon": false,
 199     "afterColon": true,
 200     "on": "colon",
 201     "mode": "strict"
 202 }
 203 ```
 204
 205 Examples of **correct** code for this rule with sample `{ "align": { } }` options:
 206
 207 ```js
 208 /*eslint key-spacing: ["error", {
 209     "align": {
 210         "beforeColon": true,
 211         "afterColon": true,
 212         "on": "colon"
 213     }
 214 }]*/
 215
 216 var obj = {
 217     "one"   : 1,
 218     "seven" : 7
 219 }
 220 ```
 221
 222 ```js
 223 /*eslint key-spacing: ["error", {
 224     "align": {
 225         "beforeColon": false,
 226         "afterColon": false,
 227         "on": "value"
 228     }
 229 }]*/
 230
 231 var obj = {
 232     "one":  1,
 233     "seven":7
 234 }
 235 ```
 236
 237 ### align and multiLine
 238
 239 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.
 240
 241 `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:
 242
 243 ```javascript
 244 var myObj = {
 245   key1: 1, // uses multiLine
 246
 247   key2: 2, // uses align (when defined)
 248   key3: 3, // uses align (when defined)
 249
 250   key4: 4 // uses multiLine
 251 }
 252
 253 ```
 254
 255 Examples of **incorrect** code for this rule with sample `{ "align": { }, "multiLine": { } }` options:
 256
 257 ```js
 258 /*eslint key-spacing: ["error", {
 259     "multiLine": {
 260         "beforeColon": false,
 261         "afterColon":true
 262     },
 263     "align": {
 264         "beforeColon": true,
 265         "afterColon": true,
 266         "on": "colon"
 267     }
 268 }]*/
 269
 270 var obj = {
 271     "myObjectFunction": function() {
 272         // Do something
 273     },
 274     "one"             : 1,
 275     "seven"           : 7
 276 }
 277 ```
 278
 279 Examples of **correct** code for this rule with sample `{ "align": { }, "multiLine": { } }` options:
 280
 281 ```js
 282 /*eslint key-spacing: ["error", {
 283     "multiLine": {
 284         "beforeColon": false,
 285         "afterColon": true
 286
 287     },
 288     "align": {
 289         "beforeColon": true,
 290         "afterColon": true,
 291         "on": "colon"
 292     }
 293 }]*/
 294
 295 var obj = {
 296     "myObjectFunction": function() {
 297         // Do something
 298         //
 299     }, // These are two separate groups, so no alignment between `myObjectFuction` and `one`
 300     "one"   : 1,
 301     "seven" : 7 // `one` and `seven` are in their own group, and therefore aligned
 302 }
 303 ```
 304
 305 ### singleLine and multiLine
 306
 307 Examples of **correct** code for this rule with sample `{ "singleLine": { }, "multiLine": { } }` options:
 308
 309 ```js
 310 /*eslint "key-spacing": [2, {
 311     "singleLine": {
 312         "beforeColon": false,
 313         "afterColon": true
 314     },
 315     "multiLine": {
 316         "beforeColon": true,
 317         "afterColon": true,
 318         "align": "colon"
 319     }
 320 }]*/
 321 var obj = { one: 1, "two": 2, three: 3 };
 322 var obj2 = {
 323     "two" : 2,
 324     three : 3
 325 };
 326 ```
 327
 328 ## When Not To Use It
 329
 330 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.