qmlformat

qmlformat is a tool that automatically formats QML files according to the QML Coding Conventions.

Options and settings

You can configure qmlformat with command-line options. There are two groups of options: those that are directly related to formatting, and those that control the behavior of the tool.

The following options only affect the tool behavior:

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

For boolean options, pass the flag on the command line or set the variable to true in the settings file to enable the behavior.

Arguments

Usage

Output

qmlformat writes the formatted version of the file to stdout. 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 {}
    }
}

is 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() {
    }
}

To group the attributes without sorting by name, use --group-attributes-together instead.

This formats the previous snippet into:

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() {
    }
}

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. You can obtain a default settings file by passing the --write-defaults flag. This generates the .qmlformat.ini file in the current working directory.

Formatting a List of Files

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

// FileList.txt
main.qml
mycomponent.qml

To use this list:

qmlformat -F FileList.txt

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.

Keep the following in mind when using formatting directives:

• Directives must be on their own line.
• 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.
• 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.