# format

> For the complete documentation index, see [llms.txt](https://kotlin.github.io/dataframe/llms.txt).

Formats the specified columns or cells within the dataframe such that they have specific CSS attributes applied to them when rendering the dataframe to HTML.

API reference: [format](https://kotlin.github.io/dataframe/api-docs/core/org.jetbrains.kotlinx.dataframe.api/format.html)

See [column selectors](columnselectors.html) for how to select the columns for this operation.

The selection of columns and rows to apply formatting to follows the [update operation](update.html). This means you can `format { }` some columns `where {}` some predicate holds true `at()` a certain range of rows `with {}` some cell attributes, just to name an example.

`.perRowCol { row, col -> }` is also available as an alternative to `.with {}`, if you want to format cells based on their relative context. See the example below for a use-case for this operation.

There are also a handful of shortcuts for common operations within `format`, such as `.linearBg(-20 to blue, 50 to red)` which is a shortcut for `.with { background(linear(it, -20 to blue, 50 to red)) }`, and `.notNull {}` which is a shortcut for `.notNull().with {}`, filtering cells to only include non-null ones.

Finally, you can decide which attributes the selected cells get. You can combine as many as you like by chaining them with the `and` infix inside the Formatting DSL. Some common examples include `background(white)`, which sets the background to `white` for a cell, `italic`, which makes the cell text italic, `textColor(linear(it, 0 to green, 100 to rgb(255, 255, 0)))`, which interpolates the text color between green and yellow based on where the value of the cell lies between 0 and 100, and finally `attr("text-align", "center")`, a custom attribute which centers the text inside the cell. See [Grammar](#grammar) for everything that's available.

The `format` function can be repeated as many times as needed and, to view the result, you can call [toHtml()/toStandaloneHtml()](tohtml.html).

Specifying a [column group](datacolumn.html#columngroup) makes all of its inner columns be formatted in the same way unless overridden.

Formatting is done additively, meaning you can add more formatting to a cell that's already formatted or override certain attributes inherited from its outer group.

Specifying a [frame column](datacolumn.html#framecolumn) at the moment does nothing ([Issue #1375](https://github.com/Kotlin/dataframe/issues/1375)); [convert](convert.html) each nested [DataFrame](dataframe.html) to a `FormattedFrame` instead:

```KOTLIN
df.convert { myFrameCol }.with {
    it.format { someCol }.with { background(green) }
}.toStandaloneHtml()
```

## Grammar

[Embedded content](resources/org.jetbrains.kotlinx.dataframe.api.FormatDocs.Grammar.ForHtml.html)

## Examples

The formatting DSL allows you to create all sorts of formatted tables. The formatting can depend on the data; for instance, to highlight how the value of a column corresponds to values of other columns:

Properties:

```KOTLIN
val ageMin = df.age.min()
val ageMax = df.age.max()

df
    .format().with { bold and textColor(black) and background(white) }
    .format { name }.with { underline }
    .format { name.lastName }.with { italic }
    .format { isHappy }.with { background(if (it) green else red) }
    .format { weight }.notNull().linearBg(50 to FormattingDsl.blue, 90 to FormattingDsl.red)
    .format { age }.perRowCol { row, col ->
        textColor(
            linear(value = col[row], from = ageMin to blue, to = ageMax to green),
        )
    }
```

Strings:

```KOTLIN
val ageMin = df.min { "age"<Int>() }
val ageMax = df.max { "age"<Int>() }

df
    .format().with { bold and textColor(black) and background(white) }
    .format("name").with { underline }
    .format { "name"["lastName"] }.with { italic }
    .format("isHappy").with {
        background(if (it as Boolean) green else red)
    }
    .format("weight").notNull().with { linearBg(it as Int, 50 to blue, 90 to red) }
    .format("age").perRowCol { row, col ->
        col as DataColumn<Int>
        textColor(
            linear(value = col[row], from = ageMin to blue, to = ageMax to green),
        )
    }
```

[Embedded content](./resources/formatExample.html)

Alternatively, you could also customize the dataframe in a data-independent manner:

```KOTLIN
df2.format().perRowCol { row, col ->
    val rowIndex = row.index()
    val colIndex = row.df().getColumnIndex(col)
    if ((rowIndex - colIndex) % 3 == 0) {
        background(darkGray) and textColor(white)
    } else {
        background(white) and textColor(black)
    }
}
```

[Embedded content](./resources/formatExampleNumbers.html)

## formatHeader

> **Tip:**
> This method is experimental and may be unstable.

Formats the specified column headers.

```KOTLIN
df
    // Format all column headers with bold
    .formatHeader().with { bold }
    // Format the "name" column (including nested) header with red text
    .formatHeader { name }.with { textColor(red) }
    // Override "name"/"lastName" column header formatting with blue text
    .formatHeader { name.lastName }.with { textColor(blue) }
    // Format all numeric column headers with underlines
    .formatHeader { colsOf<Number?>() }.with { underline }
```

[Embedded content](./resources/formatHeader.html)

