# std::formatter<basic_json> - JSON for Modern C++
Author: Niels Lohmann

Skip to content

# std::formatter<nlohmann::basic_json>

    namespace std {
        template <>
        struct formatter<nlohmann::basic_json, char>;
    }

Specialization to make JSON values formattable with `std::format` (and the other members of C++20's `<format>` header, such as `std::format_to`).

A subset of the standard format spec grammar is supported, repurposed for JSON pretty-printing; any other spec component (sign, the `0` flag, precision, `L`, a dynamic width such as `"{:{}}"`, or a trailing type character) throws `std::format_error`:

- `"{}"` serializes the value the same way as `dump()` (compact, no whitespace).
- `"{:#}"` ("alternate form") serializes the value the same way as `dump(4)` (pretty-printed with an indent of 4).
- A width, with or without `"#"` (e.g. `"{:2}"` or `"{:#2}"`), serializes the value the same way as `dump(width)` — a width on its own implies pretty-printing, since an indent size has no meaning for compact output.
- `fill-and-align` (e.g. `"{:.>#}"` or `"{:.>3}"`) picks a custom indent character, the same way as `dump(indent, indent_char)`. The alignment direction itself (`'<'`, `'>'`, `'^'`) has no separate meaning for JSON values — only the fill character before it is used, and any of the three directions is accepted.

This specialization is only available for `char`-based JSON values and only if the standard library provides `<format>`, controlled by the `JSON_HAS_STD_FORMAT` macro.

## Examples

Example

The example shows how to format JSON values with `std::format`.

    #include <format>
    #include <iostream>
    #include <nlohmann/json.hpp>

    using json = nlohmann::json;

    int main()
    {
        json j = {{"one", 1}, {"two", 2}};

        // compact formatting, like dump()
        std::cout << std::format("{}", j) << "\n\n";

        // pretty-printed formatting, like dump(4)
        std::cout << std::format("{:#}", j) << "\n\n";

        // a width sets the indent, like dump(2)
        std::cout << std::format("{:2}", j) << "\n\n";

        // fill-and-align sets the indent character, like dump(4, '.')
        std::cout << std::format("{:.>#}", j) << std::endl;
    }

Output:

    {"one":1,"two":2}

    {
        "one": 1,
        "two": 2
    }

    {
      "one": 1,
      "two": 2
    }

    {
    ...."one": 1,
    ...."two": 2
    }

## See also

- dump - serialization
- operator<<(std::ostream&) - serialize to stream
- format_as - customization point used by `fmt::format` (fmtlib)
- Serialization - the serialization article

## Version history

- Added in version 3.13.0.

July 23, 2026