Java Text Blocks

A text block is a multi-line string literal that spares you the clutter of escaped newlines and concatenation. Introduced as a preview in Java 13 and made permanent in Java 15, it lets you paste HTML, JSON, SQL, or any block of formatted text directly into your source and have it read like the real thing.

Before text blocks, a few lines of embedded markup meant a wall of \n escapes and + operators. A text block opens with three double quotes (""") followed by a line break, and everything up to the closing """ becomes the string — with leading whitespace handled intelligently.

The Triple-Quote Syntax

A text block starts with """ and a line terminator. The content begins on the next line; the opening delimiter cannot share a line with text. The block ends with another """.

// Old way: escapes and concatenation
String json = "{\n" +
              "  \"name\": \"Ada\"\n" +
              "}";

// Text block: paste it as-is
String block = """
    {
      "name": "Ada"
    }
    """;

The two produce nearly identical strings, but the text block is readable at a glance and embedded double quotes need no escaping. A text block is a String like any other — there is no separate type — so every String method works on it.

Incidental vs Essential Whitespace

The compiler distinguishes incidental whitespace (indentation added only to keep the source tidy) from essential whitespace (indentation you actually want in the value). It finds the line with the least leading whitespace — including the closing """ line — and strips that common amount from every line.

String html = """
        <p>Hi</p>
    """;
// The closing """ is indented 4 spaces, the <p> 8 spaces.
// Common minimum is 4, so the result keeps 4 leading spaces: "    <p>Hi</p>\n"

Moving the closing delimiter changes the strip amount. Putting """ at the far left removes no indentation; putting it under the deepest line removes all of it. This gives you precise control without counting spaces by hand.

Escapes and the Trailing Newline

Text blocks support the usual escape sequences, plus two that exist only for them:

Escape	Effect
`\n`, `\t`, `\"`	Standard escapes, still valid
`\` (end of line)	Line continuation — suppresses the newline that would follow
`\s`	A single space that is never stripped as incidental whitespace

A text block whose content ends on its own line includes a trailing newline; placing the closing """ on the same line as the last text omits it.

String withNewline = """
    last line
    """;          // ends with "\n"

String noNewline = """
    last line""";  // no trailing newline

Common Use Cases

Text blocks shine wherever formatted, multi-line text appears in code:

// SQL kept readable instead of one long escaped string
String query = """
    SELECT id, name, price
    FROM products
    WHERE price < ?
    ORDER BY name
    """;

// JSON payload with quotes that need no escaping
String payload = """
    {
      "user": "ada",
      "roles": ["admin", "editor"]
    }
    """;

Because the text mirrors its final shape, copy-pasting a snippet from a .sql or .json file just works, and reviewers can spot formatting mistakes immediately.

Text Blocks in Action

The example below exercises every feature: incidental-whitespace stripping, formatted() for placeholders, the lines() stream, the \s and end-of-line-\ escapes, delimiter-controlled indentation, and unescaped embedded quotes. Read the comments — each line maps to one rule above.

java— editable, runs on the server

public class TextBlockDemo {
    public static void main(String[] args) {
        // A text block: opening """ must be followed by a line terminator.
        String html = """
            <html>
                <body>
                    <p>Hello, %s!</p>
                </body>
            </html>
            """;

// Incidental indentation is stripped relative to the closing """.
        System.out.println("--- raw text block ---");
        System.out.print(html);

// Text blocks are just String instances; all String methods apply.
        String formatted = html.formatted("World");
        System.out.println("--- formatted ---");
        System.out.print(formatted);

// The line count proves the trailing newline from the closing line.
        long lines = html.lines().count();
        System.out.println("Line count: " + lines);

// \ at end of line suppresses the newline (line continuation).
        String oneLine = """
            Roses are red, \
            violets are blue.""";
        System.out.println("Continuation: " + oneLine);

// \s is a space escape that preserves trailing whitespace.
        String padded = """
            ends here:\s
            next line""";
        System.out.println("Has trailing space: "
            + (padded.split("\n")[0].endsWith(" ")));

// Closing delimiter position controls how much indent is removed.
        String indented = """
                kept
              base""";
        System.out.println("--- indentation control ---");
        System.out.println(indented);

// No special escaping needed for embedded double quotes.
        String json = """
            {"name": "Ada", "active": true}""";
        System.out.println("JSON: " + json);
    }
}

What to take from the run:

The raw block prints <html> flush at the left margin even though it was indented in the source, because the common incidental whitespace was stripped relative to the closing """.
formatted("World") substitutes the %s placeholder, proving a text block is an ordinary String you can pass to formatting methods.
Line count: 5 comes from html.lines() streaming the five content lines; the trailing newline added by the closing """ on its own line terminates the last line rather than creating an empty sixth one.
Has trailing space: true shows \s forced a space to survive that the compiler would otherwise have trimmed as incidental.
Continuation: Roses are red, violets are blue. proves a \ at end of line joined the two source lines into one, and {"name": "Ada", "active": true} printed without a single escaped quote.

Practice

In a Java text block, what determines how much leading whitespace is stripped from each line?

The line with the least indentation, including the closing triple-quote line
Always exactly four spaces, regardless of how the block is indented
The indentation of the opening triple-quote delimiter
Nothing is ever stripped; text blocks preserve all whitespace literally