Configuration

Options name in this documentation are in camel case. If you're using Malva as a Rust crate, please use snake case instead.

`printWidth`

The line width limitation that Malva should (but not must) avoid exceeding. Malva will try its best to keep line width less than this value, but it may exceed for some cases, for example, a very very long single word.

Default option is 80.

Example for `80`

Playground

a {
  font: ultra-condensed small-caps 1.2em "Fira Sans", sans-serif;
}

Example for `40`

Playground

a {
  font:
    ultra-condensed small-caps 1.2em
    "Fira Sans",
    sans-serif;
}

`useTabs`

Specify use space or tab for indentation.

Default option is false.

Example for `false`

Playground

Example for `true`

Playground

`indentWidth`

Size of indentation. When enabled useTabs, this option may be disregarded, since only one tab will be inserted when indented once.

Default option is 2. This can't be zero.

Examples below will are based on useTabs: false.

Example for `2`

Playground

a {
  text-decoration: none;
}

Example for `4`

Playground

a {
    text-decoration: none;
}

`lineBreak`

Specify use \n (LF) or \r\n (CRLF) for line break.

Default option is "lf". Possible options are "lf" and "crlf".

Example for `"lf"`

Playground

Example for `"crlf"`

Playground

`hexCase`

Control the case of hex color values.

Possible options:

"lower": Hex color values will be converted to lower case.
"upper": Hex color values will be converted to upper case.
"ignore": Hex color values will be kept as-is.

Default option is "lower".

Example for `"lower"`

Playground

a {
  background: #fff;
}

Example for `"upper"`

Playground

a {
  background: #FFF;
}

Example for `"ignore"`

Playground

a {
  background: #FfF;
}

`hexColorLength`

Control the hex color values in short-hand form or long-hand form.

Possible options:

null: Hex color values will be kept as-is.
"short": Hex color values will be converted to short-hand form.
"long": Hex color values will be converted to long-hand form.

Default option is null.

Example for `null`

Playground

a {
  color: #fff;
  color: #ffffff;
}

Example for `"short"`

Playground

a {
  color: #fff;
}

Example for `"long"`

Playground

a {
  color: #ffffff;
}

`quotes`

Control the quotes of strings.

Possible options:

"alwaysDouble": Always use double quotes. Double quotes in strings will be escaped.
"alwaysSingle": Always use single quotes. Single quotes in strings will be escaped.
"preferDouble": Use double quotes as possible. However if there're double quotes in strings, quotes will be kept as-is.
"preferSingle": Use single quotes as possible. However if there're single quotes in strings, quotes will be kept as-is.

Default option is "alwaysDouble".

Example for `"alwaysDouble"`

Playground

::before {
  content: "";
  content: "\"";
}

Example for `"alwaysSingle"`

Playground

::before {
  content: '';
  content: '\'';
}

Example for `"preferDouble"`

Playground

::before {
  content: "";
  content: '"';
}

Example for `"preferSingle"`

Playground

::before {
  content: '';
  content: "'";
}

`operatorLinebreak`

Control whether line break should come before or after operators.

Possible options:

"before": Line break will come before operators.
"after": Line break will come after operators.

Default option is "after".

Example for `"before"`

Playground

a {
  width: calc(
    100%
      - (
      var(--sidebar-width) + var(--padding-horizontal) + var(--border-width)
        + var(--margin-horizontal)
        + var(--scrollbar-width)
    )
  );
}

Example for `"after"`

Playground

a {
  width: calc(
    100% -
      (
      var(--sidebar-width) + var(--padding-horizontal) + var(--border-width) +
        var(--margin-horizontal) +
        var(--scrollbar-width)
    )
  );
}

`blockSelectorLinebreak`

Control line break behavior after selector commas.

Possible options:

"always": Always insert line break after comma.
"consistent": If the whole selector can be put on a single line, there won't be line breaks; otherwise, there will be line breaks after each comma.
"wrap": Selector will be put on one line as possible. Once it exceeds printWidth, line break will be inserted where the code exceeds printWidth.

Default option is "consistent".

Example for `"always"`

Playground

h1,
h2,
h3,
h4,
h5,
h6 {}

Example for `"consistent"`

Playground

In this example, the first selector can be put on one line, but the second selector can't, so there will be line breaks.

h1, h2, h3, h4, h5, h6 {}
.very-very-very-very-very-very-long-selector,
.very-very-very-very-very-very-very-very-very-long-selector {}

Example for `"wrap"`

Playground

html, body, div, span, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote,
pre, abbr, address, cite, code, del, dfn, em, img, ins, kbd, q, samp, small,
strong, sub, sup, var, b, i, dl, dt, dd, ol, ul, li, fieldset, form, label,
legend, table, caption, tbody, tfoot, thead, tr, th, td, article, aside, canvas,
details, figcaption, figure, footer, header, hgroup, menu, nav, section,
summary, time, mark, audio, video {}

Overriding or ignoring

Selector of specific block can be overridden or ignored by adding a comment directive above the selector.

For example, to ignore it:

/* malva-selector-override ignore */
h1, h2,
h3, h4,
h5, h6 {}

Or, to override with different options:

/* malva-selector-override always */
.container,
.btn {}

This selector will be formatted as "always" disregarding the configuration.

To customize the comment directive text, see the selectorOverrideCommentDirective option.

`omitNumberLeadingZero`

Control whether omit leading zero before dot of numbers or not.

Default option is false.

Example for `false`

Playground

a {
  width: 0.1px;
}

Example for `true`

Playground

a {
  width: .1px;
}

`trailingComma`

Control whether trailing comma should be inserted or not.

This only affects Sass list, Sass map, Sass parameters/arguments list, Less list and Less parameters/arguments list. CSS functions won't respect this option.

Default option is false.

Example for `false`

Playground

$config: (
  themes: (
    mist: (header: #dcfac0, content: #00968b, footer: #85c79c),
    $spring: (header: #f4fac7, content: #c2454e, footer: #ffb158)
  )
);

Example for `true`

Playground

$config: (
  themes: (
    mist: (header: #dcfac0, content: #00968b, footer: #85c79c),
    $spring: (header: #f4fac7, content: #c2454e, footer: #ffb158),
  ),
);

`formatComments`

Control whether whitespace should be inserted at the beginning and end of comments.

Though this option is set to false, comments contain leading or trailing whitespace will still be kept as-is.

Default option is false.

This option is renamed from padComments which is deprecated.

Example for `false`

Playground

/*comments*/
/* comments */

Example for `true`

Playground

/* comments */
/* comments */

`alignComments`

Control whether to tweak multi-line comments indentation.

Default option value is true.

Example for `false`

Playground

When formatting the 4-space indented CSS into 2-space indented CSS:

a {
    /* comment line 1
       comment line 2
       comment line 3
    */
    text-decoration: none;
}

will be formatted as:

a {
  /* comment line 1
       comment line 2
       comment line 3
    */
  text-decoration: none;
}

Example for `true`

Playground

When formatting the 4-space indented CSS into 2-space indented CSS:

a {
    /* comment line 1
       comment line 2
       comment line 3
    */
    text-decoration: none;
}

will be formatted as:

a {
  /* comment line 1
     comment line 2
     comment line 3
  */
  text-decoration: none;
}

`linebreakInPseudoParens`

Control whether line break should be inserted in pseudo class/element parens or not if current line is too long.

Default option is false.

Example for `false`

Playground

:where(#p0:checked ~ #play:checked ~ #c1:checked, #p1:checked
  ~ #play:checked
  ~ #c2:checked, #p2:checked ~ #play:checked ~ #cO:checked) {}

Example for `true`

Playground

:where(
  #p0:checked ~ #play:checked ~ #c1:checked,
    #p1:checked ~ #play:checked ~ #c2:checked,
    #p2:checked ~ #play:checked ~ #cO:checked
) {}

`declarationOrder`

Control the strategy of sorting CSS declarations (a.k.a. properties). If it's null, it won't sort CSS declarations.

Here're the available strategies:

alphabetical: Order in a simple alphabetical manner from a - z. This strategy will also sort unknown properties.
smacss: Order from most important, flow affecting properties, to least important properties. Unknown properties won't be sorted.
concentric: Order properties applying outside the box model, moving inward to intrinsic changes. Unknown properties won't be sorted.

For more detail, please read https://github.com/Siilwyn/css-declaration-sorter.

Default option value is null.

Notes

For all strategies, custom properties (whose name starts with --) won't be sorted.
It will only sort adjacent CSS declarations. For example:
```
div {
  width: 0;
  height: 0;
  span {}
  min-width: 0;
  min-height: 0;
}
```
Those declarations above the span {} and those declarations below the span {} will be sorted separately.

Example for `"alphabetical"`

Playground

div {
  display: flex;
  height: 0;
  width: 0;
}

Example for `"smacss"`

Playground

div {
  display: flex;
  width: 0;
  height: 0;
}

Example for `"concentric"`

Playground

div {
  display: flex;
  width: 0;
  height: 0;
}

`singleLineBlockThreshold`

Control the threshold value for putting block on a single line. If the number of statements in a block is less than or equal to this value, the block will be put on a single line as possible, but when the code can't fit on single line, it will still break into multiple lines.

This is especially useful for increasing readability when writing atomic CSS. For example:

.border-0 { border-width: 0px; }
.border-1 { border-width: 1px; }
.border-2 { border-width: 2px; }
.border-3 { border-width: 3px; }
.border-4 { border-width: 4px; }
.border-5 { border-width: 5px; }

Default option value is null which means always break into multiple lines. The option value can be an integer which is greater than or equal to 0.

Example for `null`

Playground

a {
  /* comment */
}

a {
  width: 0;
}

Example for `1`

Playground

a { /* comment */ }

a { width: 0; }

a {
  width: 0;
  height: 0;
}

Example for `2`

Playground

a { /* comment */ }

a { width: 0; }

a { width: 0; height: 0; }

`keyframeSelectorNotation`

Control whether to use percentage or keyword (from and to) notation as keyframe selectors.

Possible options:

null: Keyframe selector notation will be kept as-is.
"keyword": Use keyword notation. This only affects 0% and 100%. For other percentage values, they will be kept as-is.
"percentage": Use percentage notation.

Default option is null.

Example for `null`

Playground

@keyframes foo {
  from {}
  50% {}
  100% {}
}

Example for `"keyword"`

Playground

@keyframes foo {
  from {}
  50% {}
  to {}
}

Example for `"percentage"`

Playground

@keyframes foo {
  0% {}
  50% {}
  100% {}
}

`attrValueQuotes`

Control whether should add quotes to attribute value in selector or not if it's not quoted.

Possible options:

"always": Always add quotes.
"ignore": Don't add quotes to those that're not quoted. For quoted value, quotes won't be removed.

Default option is "always".

Example for `"always"`

Playground

[key="value"] {}

Example for `"ignore"`

Playground

[key=value] {}

`preferSingleLine`

Control whether items should be placed on single line as possible, even they're originally on multiple lines.

Default option is false.

This global option can be overridden by different syntax nodes:

selectors.preferSingleLine (blockSelectorLinebreak must be "consistent", otherwise this will be ignored)
functionArgs.preferSingleLine
sassContentAtRule.preferSingleLine
sassIncludeAtRule.preferSingleLine
sassMap.preferSingleLine
sassModuleConfig.preferSingleLine
sassParams.preferSingleLine
lessImportOptions.preferSingleLine
lessMixinArgs.preferSingleLine
lessMixinParams.preferSingleLine

Given the following example CSS:

a {
  color: rgb(
    0,
    0, 0
  );
}

Example for `false`

Playground

a {
  color: rgb(
    0,
    0,
    0
  );
}

Example for `true`

Playground

a {
  color: rgb(0, 0, 0);
}

`singleLineTopLevelDeclarations`

Control whether to force to format all top-level declarations on a single line.

When this option is true, trailing semicolons are removed.

Most of the time, you don't need to set this option, because declarations at top level are invalid, but if you're formatting HTML's style attribute, you may want to set this to true.

Default option is false.

Example for `false`

Playground

width: 100px;
height: 100px;

Example for `true`

Playground

width: 100px; height: 100px

`selectorOverrideCommentDirective`

Text directive for overriding selector formatting.

This can be used to ignore formatting selector of a specific qualified rule without ignoring the whole qualified rule. Or, it can be used to format a specific selector in a different way. For example, you're resetting CSS with many tag name selectors, then you can use "wrap" style to format this selector only without affecting other selectors.

Suppose blockSelectorLineBreak is "always" in configuration, with the following CSS:

/* malva-selector-override wrap */
html, body, div, span, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote,
pre, abbr {}

.btn,
.btn-primary {}

Note that nested qualified rules won't be affected:

/* malva-selector-override wrap */
html, body, div, span, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote,
pre, abbr {
  /* nested qualified rule is still respecting configuration, not overriden value */
  .btn,
  .btn-primary {}
}

Default is "malva-selector-override".

`ignoreCommentDirective`

Text directive for ignoring formatting specific statement.

Default is "malva-ignore".

Example

Playground

/* malva-ignore */
a,b{
  width  :  0;
}

`ignoreFileCommentDirective`

Text directive for ignoring formatting a whole file.

Default is "malva-ignore-file", but if you're using as a dprint plugin, it will be "dprint-ignore-file".

Example

Playground

/* malva-ignore-file */
a,b{
  width  :  0;
}

Malva Documentation