- Qt 6.12
- Qt Qml
- Qt Qml Tooling
- qmlformat
- Qt 6.12.0 Reference Documentation

qmltc ◦ qmltyperegistrar

# qmlformat

qmlformat is a tool that automatically formats QML files in accordance with the QML Coding Conventions.

Usage:
qmlformat [options] arguments

### Options and settings

qmlformat can be configured via command line options. There are two groups of options: Those which are directly related to formatting, and those which control the behavior of the tool.

The following options only affect the tool behavior:

Command Line Option | Description
--- | ---
`-h`, `--help` | Displays help on commandline options.
`--help-all` | Displays help, including generic Qt options.
`-v`, `--version` | Displays version information.
`-V`, `--verbose` | Verbose mode. Outputs more detailed information.
`--write-defaults` | Writes defaults settings to .qmlformat.ini and exits (Warning: This will overwrite any existing settings and comments!)
`--output-options` |  | Output all available options, their default value and a hint of values or types
`--ignore-settings` | Ignores all settings files and only takes command line options into consideration
`-i`, `--inplace` | Edit file in-place instead of outputting to stdout.
`-f`, `--force` | Continue even if an error has occurred.
`-F`, `--files <file>` | Format all files listed in file, in-place

The next group of options controls how files should be formatted, and can additionally also be controlled via a settings file.:

Command Line Option | Setting Name | Default State/Value | Description
--- | --- | --- | ---
`-t`, `--tabs` | UseTabs | disabled/false | Use tabs instead of spaces. In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to "true".
`-w`, `--indent-width <width>` | IndentWidth | 4 | How many spaces are used when indenting.
`-W`, `--column-width <width>` | MaxColumnWidth | -1 | Breaks the line into multiple lines if it exceeds the specified width. Use -1 to disable line wrapping. (default).
`-n`, `--normalize` | NormalizeOrder | disabled/false | Reorders and sorts the attributes of the objects according to the QML Coding Guidelines. Incompatible with `--group-attributes-together`. In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to "true".
`-l`, `--newline <newline>` | NewlineType | native | Overrides the new line format to use (`native`, `macos`, `unix`, `windows`).
`-S`, `--sort-imports` | SortImports | disabled/false | Sort imports alphabetically (Warning: this might change semantics if a given name identifies types in multiple modules!). In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to "true".
`--objects-spacing` | ObjectsSpacing | disabled/false | Ensure spaces between objects (only works with `normalize` or `group-attributes-together`). In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to "true".
`--functions-spacing` | FunctionsSpacing | disabled/false | Ensure spaces between functions (only works with `normalize` or `group-attributes-together`). In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to "true".
`--group-attributes-together` | GroupAttributesTogether | disabled/false | Reorders but does not sort the attributes of the objects according to the QML Coding Guidelines. Incompatible with `--normalize`. In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to "true".
`--single-line-empty-objects` | SingleLineEmptyObjects | disabled/false | Write empty objects on a single line (only works with `normalize` or `group-attributes-together`). In a command line invocation, the behavior can be enabled by passing the flag. In a settings file, the behavior can be enabled by setting the relevant variable to "true".
`--semicolon-rule` | SemicolonRule | always | Customizes the addition of semicolons at the end of JS statements (`always`, `essential`). Note: See Semicolon Rule for more details.

### Arguments

Arguments:
filenames

### Details

qmlformat is flexible and can be configured according to your needs.

#### Output

qmlformat writes the formatted version of the file to stdout. If you wish to have your file updated in-place specify the `-i` flag.

#### Grouping Properties, Functions, and Signals Together

With `-n` or `--normalize` flag, qmlformat groups and sorts all properties, functions, and signals by name, instead of retaining the existing order. For example:

     import QtQuick

     QtObject {
         signal s2()
         property int h
         function z() {}
         property int w
         function y() {}
         id: asdf
         signal s1()

         property Item myItem2: Item {
             TextEdit {}
             Rectangle {}
         }
         property Item myItem: Item {
             Rectangle {}
             TextEdit {}
         }
     }

will be formatted to:

     import QtQuick

     QtObject {
         id: asdf

         property int h
         property Item myItem: Item {
             Rectangle {
             }
             TextEdit {
             }
         }
         property Item myItem2: Item {
             TextEdit {
             }
             Rectangle {
             }
         }
         property int w

         signal s1
         signal s2

         function y() {
         }
         function z() {
         }
     }
     \enqml

     To group the attributes without sorting by name, use \c{--group-attributes-together} instead.
     This formats the previous snippet into:
     \qml
     import QtQuick

     QtObject {
         id: asdf

         property int h
         property int w
         property Item myItem2: Item {
             TextEdit {
             }
             Rectangle {
             }
         }
         property Item myItem: Item {
             Rectangle {
             }
             TextEdit {
             }
         }

         signal s2
         signal s1

         function z() {
         }
         function y() {
         }
     }

Note that this option takes precedence over `--normalize`.

#### Settings File

You can configure qmlformat by including a settings file `.qmlformat.ini` in your project source or in the parent directories of your project source folder. A default settings file can be obtained by passing the `--write-defaults` flag. This generates the `.qmlformat.ini` file in the current working directory.

Warning: `--write-defaults` will overwrite any existing settings and comments!

#### Formatting a List of Files

While you can pass a list of files to be formatted as arguments, qmlformat provides `-F` option to format a set of files stored in a file. In this case, formatting will happen inplace.

     // FileList.txt
     main.qml
     mycomponent.qml

Then, use it like

     qmlformat -F FileList.txt

Note: If the file contains an invalid entry, for example, a file path that doesn't exist or a valid file path but the content is an invalid qml document, then `qmlformat` will error out for that particular entry. It will still format the valid file entries in place.

Warning: If you provide -F option, qmlformat will ignore the positional arguments.

#### Semicolon Rule

The `--semicolon-rule` option allows you to customize the addition of semicolons at the end of JS statements. The following values are accepted:

- `always` - Always add semicolons (default).
- `essential` - Remove semicolons unless omitting them would cause issues.

### Disabling Formatting with Comments

You can temporarily disable qmlformat using special comments.

- `// qmlformat off` turns off formatting from that line onward
- `// qmlformat on` turns on formatting after you turned it off

This lets you preserve hand-tuned code or complex structures without `qmlformat` changing their layout. Formatting remains off until the next `// qmlformat on` comment, or until the end of the file if no re-enable is found.

Note: Directives must be on their own line.

Note: Nested directives are not supported. Only the first `// qmlformat off` and the next `// qmlformat on` are considered. Any additional directives inside a disabled region are ignored.

Note: The directives are ignored in normalized formatting mode, when `sortImports` is enabled, or when any option that reorders the original document is used. In these cases, formatting is always applied.

qmltc ◦ qmltyperegistrar