Package {condformat}

Type:	Package
Title:	Conditional Formatting in Data Frames
Version:	0.11.0
Date:	2026-07-09
URL:	https://zeehio.github.io/condformat/, https://github.com/zeehio/condformat
BugReports:	https://github.com/zeehio/condformat/issues
Description:	Apply and visualize conditional formatting to data frames in R. It renders a data frame with cells formatted according to criteria defined by rules, using a tidy evaluation syntax. The table is printed either opening a web browser or within the 'RStudio' viewer if available. The conditional formatting rules allow to highlight cells matching a condition or add a gradient background to a given column. This package supports both 'HTML' and 'LaTeX' outputs in 'knitr' reports, and exporting to an 'xlsx' file.
License:	BSD_3_clause + file LICENSE
NeedsCompilation:	no
Depends:	R (≥ 4.1)
Imports:	dplyr (≥ 1.1.4), grDevices, htmlTable (≥ 2.4.3), htmltools (≥ 0.5.8.1), knitr (≥ 1.50), rlang (≥ 1.1.6), scales (≥ 1.4.0), tibble (≥ 3.3.0), tidyselect (≥ 1.2.1)
Suggests:	gridExtra (≥ 2.3), gtable (≥ 0.3.6), openxlsx (≥ 4.2.8), promises, rmarkdown (≥ 2.29), shiny (≥ 1.11.1), testthat (≥ 3.2.3), vdiffr (≥ 1.0.8)
VignetteBuilder:	knitr
Encoding:	UTF-8
Config/roxygen2/version:	8.0.0
Packaged:	2026-07-09 20:47:53 UTC; root
Author:	Sergio Oller Moreno [aut, cph, cre]
Maintainer:	Sergio Oller Moreno <sergioller@gmail.com>
Repository:	CRAN
Date/Publication:	2026-07-09 21:10:02 UTC

How to export a cf_field to CSS

Description

This method is exported so package users can generate their own rules

Usage

cf_field_to_css(cf_field, xview, css_fields, unlocked)

Arguments

Value

A list with two elements: css_fields and unlocked (with updated values)

How to export a cf_field to grob

Description

This method is exported so package users can generate their own rules

Usage

cf_field_to_gtable(
  cf_field,
  xview,
  gridobj,
  unlocked,
  has_rownames,
  has_colnames
)

Arguments

Value

A list with two elements: gridobj and unlocked (with updated values)

How to export cf values to latex

Description

How to export cf values to latex

Usage

cf_field_to_latex(cf_field, xview, unlocked)

Arguments

Value

A list with two character matrices named before and after. Both of these matrices must be of the same size as xview.

Conditional formatting for data frames

Description

A condformat_tbl object is a data frame with attributes regarding the formatting of their cells, that can be viewed when the condformat_tbl object is printed.

Usage

condformat(x)

Arguments

Value

The condformat_tbl object. This object can be piped to apply conditional formatting rules. It can also be used as a conventional data frame.

The condformat_tbl print method generates an htmlTable, to be viewed using the 'RStudio Viewer' or an 'HTML browser', as available.

Examples

data(iris)
cf <- condformat(iris[1:5,])
## Not run: 
print(cf)

## End(Not run)

cf <- condformat(iris[1:5,]) |> rule_fill_gradient(Sepal.Length)
## Not run: 
print(cf)

## End(Not run)

cf <- condformat(iris[1:5,]) |>
 rule_fill_discrete(Sepal.Length, expression=Sepal.Width > 2)
## Not run: 
print(cf)

## End(Not run)

Shiny bindings for condformat

Description

Output and render functions for using condformat within Shiny applications and interactive Rmd documents.

Usage

condformatOutput(outputId, ...)

renderCondformat(expr, env = parent.frame(), quoted = FALSE)

condformat_example(display.mode = "normal")

Arguments

Writes the table to an Excel workbook

Description

Requires the openxlsx package (install.packages("openxlsx")).

Usage

condformat2excel(
  x,
  filename,
  sheet_name = "Sheet1",
  overwrite_wb = FALSE,
  overwrite_sheet = TRUE
)

Arguments

See Also

condformat2excelsheet(), to write into a worksheet of an openxlsx workbook you're building yourself, so you can add more sheets or apply extra openxlsx formatting before saving.

Writes the table to a worksheet of an existing Excel workbook

Description

Requires the openxlsx package (install.packages("openxlsx")).

Usage

condformat2excelsheet(x, workbook, sheet_name)

Arguments

Details

Unlike condformat2excel(), this does not create the workbook or save it to disk: you pass in an openxlsx workbook (and an already-added worksheet) yourself, so you can add other sheets, or apply additional openxlsx formatting, before saving it with openxlsx::saveWorkbook().

This function applies its own styling (fill colour, bold, font colour) to every cell using stack = TRUE, so it merges with, rather than replaces, any formatting you already applied (e.g. a number format on a Date column, set either by you or automatically by openxlsx::writeData()).

openxlsx::addStyle() itself defaults to replacing, not merging, any style already present at a cell. So if you add your own openxlsx formatting after calling this function, remember to pass stack = TRUE to your own call too, or it will silently replace condformat's own styling instead of combining with it. See the example below.

See Also

condformat2excel(), which creates the workbook, writes a single sheet with this function, and saves it to disk in one call.

Examples

data(iris)
cf <- condformat(iris[1:5, ]) |>
  rule_fill_gradient(Sepal.Width)
## Not run: 
workbook <- openxlsx::createWorkbook(creator = "")
openxlsx::addWorksheet(workbook, sheetName = "iris")
condformat2excelsheet(cf, workbook, "iris")
# Combine condformat's own fill colour on Sepal.Width (column 2) with a
# percentage number format, using stack = TRUE so it doesn't replace
# condformat's own styling:
openxlsx::addStyle(
  workbook, "iris",
  style = openxlsx::createStyle(numFmt = "0%"),
  rows = 2:6, cols = 2, stack = TRUE
)
openxlsx::saveWorkbook(workbook, file = "iris.xlsx", overwrite = TRUE)

## End(Not run)

Converts the table to a grid object

Description

Requires the gridExtra package (install.packages("gridExtra")).

Usage

condformat2grob(x, draw = TRUE)

Arguments

Value

the grid object

Examples

library(condformat)
if (requireNamespace("gridExtra", quietly = TRUE)) {
  data.frame(Student = c("Alice", "Bob", "Charlie"),
             Evaluation = c("Great", "Well done", "Good job!")) |>
   condformat() |>
   condformat2grob()
}

Converts the table to a htmlTable object

Description

Converts the table to a htmlTable object

Usage

condformat2html(x)

Arguments

Value

the htmlTable object

Examples

data(iris)
cf <- condformat2html(condformat(iris[1:5,]))
## Not run: 
print(cf)

## End(Not run)

Converts the table to LaTeX code

Description

Converts the table to LaTeX code

Usage

condformat2latex(x)

Arguments

Value

A character vector of the table source code

Converts the table to a htmlTableWidget

Description

Converts the table to a htmlTableWidget

Usage

condformat2widget(x, ...)

Arguments

Value

the htmlTable widget

Examples

## Not run: 
data(iris)
cf <- condformat2widget(condformat(iris[1:5,]))
\dontrun{
print(cf)
}

## End(Not run)

Print method for knitr, exporting to HTML or LaTeX as needed

Description

Print method for knitr, exporting to HTML or LaTeX as needed

Usage

## S3 method for class 'condformat_tbl'
knit_print(x, ...)

Arguments

Prints the data frame in an HTML page and shows it.

Description

Prints the data frame in an HTML page and shows it.

Usage

## S3 method for class 'condformat_tbl'
print(x, ..., paginate = TRUE)

Arguments

Value

the value returned by htmlTable::htmlTable()

Examples

data(iris)
## Not run: 
print(condformat(iris[1:5,]))

## End(Not run)

Apply a CSS style property as a conditional formatting rule

Description

Apply a CSS style property as a conditional formatting rule

Usage

rule_css(x, columns, expression, css_field, na.value = "", lockcells = FALSE)

Arguments

See Also

Other rule: rule_fill_bar(), rule_fill_discrete(), rule_fill_gradient(), rule_fill_gradient2(), rule_text_bold(), rule_text_color()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 51:55, 101:105),]) |>
  rule_css(Species, expression = ifelse(Species == "setosa", "red", "darkgreen"),
           css_field = "color")
## Not run: 
print(cf)

## End(Not run)

Fill column with a bar of a length proportional to a value

Description

Fills the background of a column cell using a bar proportional to the value of the cell

Usage

rule_fill_bar(
  x,
  columns,
  expression,
  low = "darkgreen",
  high = "white",
  background = "white",
  na.value = "gray",
  limits = NA,
  lockcells = FALSE
)

Arguments

Details

In Excel output (condformat2excel()/condformat2excelsheet()), this is rendered using Excel's own native data bar conditional formatting, coloured with low (high, background and lockcells don't apply to it, since Excel data bars are solid-coloured and are a workbook-level conditional formatting rule, not a per-cell style). This only happens when expression is left at its default (or explicitly .col): Excel data bars always reflect a cell's own displayed value against a range, so a custom expression (e.g. sizing one column's bar by another column's values) can't be replicated there and is skipped, with a warning; the cell's flat background/na.value colours are still applied in that case.

Value

The condformat_tbl object, with the added formatting information

See Also

Other rule: rule_css(), rule_fill_discrete(), rule_fill_gradient(), rule_fill_gradient2(), rule_text_bold(), rule_text_color()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) |> rule_fill_bar("Sepal.Length")
## Not run: 
print(cf)

## End(Not run)

Fill column with discrete colors

Description

Fills a column or columns of a data frame using a discrete colour palette, based on an expression.

Usage

rule_fill_discrete(
  x,
  columns,
  expression,
  colours = NA,
  na.value = "#FFFFFF",
  h = c(0, 360) + 15,
  c = 100,
  l = 65,
  h.start = 0,
  direction = 1,
  lockcells = FALSE
)

Arguments

Value

The condformat_tbl object, with the added formatting information

See Also

Other rule: rule_css(), rule_fill_bar(), rule_fill_gradient(), rule_fill_gradient2(), rule_text_bold(), rule_text_color()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) |>
 rule_fill_discrete("Species", colours = c("setosa" = "red",
                                         "versicolor" = "blue",
                                         "virginica" = "green")) |>
 rule_fill_discrete("Sepal.Length", expression = Sepal.Length > 4.6,
                    colours=c("TRUE"="red"))
## Not run: 
print(cf)

## End(Not run)

cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) |>
 rule_fill_discrete(c(starts_with("Sepal"), starts_with("Petal")),
                    expression = Sepal.Length > 4.6,
                    colours=c("TRUE"="red"))
## Not run: 
print(cf)

## End(Not run)

# .col lets each selected column use its own values in the expression:
cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) |>
 rule_fill_discrete(c(Sepal.Length, Sepal.Width), .col > 3,
                    colours = c("TRUE" = "red"))
## Not run: 
print(cf)

## End(Not run)

Fill column with sequential colour gradient

Description

Fills the background color of a column using a gradient based on the values given by an expression

Usage

rule_fill_gradient(
  x,
  columns,
  expression,
  low = "#132B43",
  high = "#56B1F7",
  space = "Lab",
  na.value = "#7F7F7F",
  limits = NA,
  lockcells = FALSE
)

Arguments

Value

The condformat_tbl object, with the added formatting information

See Also

Other rule: rule_css(), rule_fill_bar(), rule_fill_discrete(), rule_fill_gradient2(), rule_text_bold(), rule_text_color()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) |>
  rule_fill_gradient(Sepal.Length) |>
  rule_fill_gradient(Species, expression=Sepal.Length - Sepal.Width)
## Not run: 
print(cf)

## End(Not run)

cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) |>
  rule_fill_gradient("Petal.Length") |>
  rule_fill_gradient(starts_with("Sepal"), expression=Sepal.Length - Sepal.Width)
## Not run: 
print(cf)

## End(Not run)

Fill column with sequential color gradient

Description

Fills the background color of a column using a gradient based on the values given by an expression

Usage

rule_fill_gradient2(
  x,
  columns,
  expression,
  low = scales::muted("red"),
  mid = "white",
  high = scales::muted("blue"),
  midpoint = NA,
  space = "Lab",
  na.value = "#7F7F7F",
  limits = NA,
  lockcells = FALSE
)

Arguments

Value

The condformat_tbl object, with the added formatting information

See Also

Other rule: rule_css(), rule_fill_bar(), rule_fill_discrete(), rule_fill_gradient(), rule_text_bold(), rule_text_color()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) |>
 rule_fill_gradient2(Sepal.Length) |>
 rule_fill_gradient2(Species, expression=Sepal.Length - Sepal.Width)
## Not run: 
print(cf)

## End(Not run)

cf <- condformat(iris[c(1:5, 70:75, 120:125), ]) |>
  rule_fill_gradient2("Petal.Length") |>
  rule_fill_gradient2(starts_with("Sepal"), expression=Sepal.Length - Sepal.Width)
## Not run: 
print(cf)

## End(Not run)

Use bold text if a condition is met

Description

Use bold text if a condition is met

Usage

rule_text_bold(x, columns, expression, na.bold = FALSE, lockcells = FALSE)

Arguments

See Also

Other rule: rule_css(), rule_fill_bar(), rule_fill_discrete(), rule_fill_gradient(), rule_fill_gradient2(), rule_text_color()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 51:55, 101:105),]) |>
  rule_text_bold(Species, expression = Species == "setosa")
## Not run: 
print(cf)

## End(Not run)

Give a color to the text according to some expression

Description

Give a color to the text according to some expression

Usage

rule_text_color(x, columns, expression, na.color = "", lockcells = FALSE)

Arguments

See Also

Other rule: rule_css(), rule_fill_bar(), rule_fill_discrete(), rule_fill_gradient(), rule_fill_gradient2(), rule_text_bold()

Examples

data(iris)
cf <- condformat(iris[c(1:5, 51:55, 101:105),]) |>
  rule_text_color(Species, expression = ifelse(Species == "setosa", "blue", ""))
## Not run: 
print(cf)

## End(Not run)

Selects the variables to be printed

Description

Keeps the variables you mention in the printed table. Compared to dplyr::select(), show_columns does not remove the columns from the data frame, so formatting rules can still depend on them.

Usage

show_columns(x, columns, col_names)

Arguments

Value

The condformat object with the rule added

See Also

dplyr::select()

Examples

data(iris)
x <- head(iris)

# Include some columns:
cf <- condformat(x) |> show_columns(c(Sepal.Length, Sepal.Width, Species))
## Not run: 
print(cf)

## End(Not run)
cf <- condformat(x) |> show_columns(c("Sepal.Length", "Sepal.Width", "Species"))
## Not run: 
print(cf)

## End(Not run)

# Rename columns:
cf <- condformat(x) |>
  show_columns(c(Sepal.Length, Species),
               col_names = c("Length", "Spec."))
## Not run: 
print(cf)

## End(Not run)

# Exclude some columns:
cf <- condformat(x) |> show_columns(c(-Petal.Length, -Petal.Width))
## Not run: 
print(cf)

## End(Not run)

cf <- condformat(x) |> show_columns(c(starts_with("Petal"), Species))
## Not run: 
print(cf)

## End(Not run)

petal_width <- "Petal.Width"
cf <- condformat(x) |> show_columns(!! petal_width)
## Not run: 
print(cf)

## End(Not run)

Selects the rows to be printed

Description

Keeps the rows you mention in the printed table. Compared to dplyr::filter(), show_rows does not remove the rows from the actual data frame, they are removed only for printing.

Usage

show_rows(x, ...)

Arguments

Value

A condformat_show_rows object, usually to be added to a condformat_tbl object as shown in the examples

See Also

dplyr::filter()

Examples

library(condformat)
data(iris)
x <- head(iris)
cf <- condformat(x) |> show_rows(Sepal.Length > 4.5, Species == "setosa")
## Not run: 
print(cf)

## End(Not run)
# Use it programatically
expr_as_text <- 'Sepal.Length > 4.5'
expr <- rlang::parse_expr(expr_as_text)
cf <- condformat(x) |> show_rows(!! expr)
## Not run: 
print(cf)

## End(Not run)
# With multiple arguments:
expr_as_text <- c('Sepal.Length > 4.5', 'Species == "setosa"')
exprs <- lapply(expr_as_text, rlang::parse_expr)
cf <- condformat(x) |> show_rows(!!! exprs)
## Not run: 
print(cf)

## End(Not run)

Sets the caption of a condformat object

Description

The advantage with respect to theme_htmlTable(caption = "My table") is that this works with HTML and LaTeX outputs

Usage

theme_caption(x, caption = "")

Arguments

Examples

data(iris)
cf <- condformat(head(iris)) |>
  theme_caption(caption = "My Caption")
## Not run: 
print(cf)

## End(Not run)

Customizes appearance of condformat object

Description

This is only used on grob output, which requires the gridExtra package (install.packages("gridExtra")).

Usage

theme_grob(x, ...)

Arguments

See Also

gridExtra::tableGrob()

Examples

data(iris)
if (requireNamespace("gridExtra", quietly = TRUE)) {
  cf <- condformat(head(iris)) |>
    theme_grob(
      rows = NULL,
      theme = gridExtra::ttheme_default(base_size = 10, base_colour = "red")
    )
  condformat2grob(cf)
}

Customizes appearance of condformat object

Description

Customizes appearance of condformat object

Usage

theme_htmlTable(x, ...)

Arguments

See Also

htmlTable::htmlTable()

Examples

data(iris)
cf <- condformat(head(iris)) |>
  theme_htmlTable(caption="Table 1: My iris table", rnames=FALSE)
## Not run: 
print(cf)

## End(Not run)

Customizes appearance of condformat object

Description

Customizes appearance of condformat object

Usage

theme_htmlWidget(x, ...)

Arguments

See Also

htmlTable::htmlTable()

Examples

data(iris)
cf <- condformat(head(iris)) |>
  theme_htmlWidget(number_of_entries = c(10, 25, 100),
                   width = NULL, height = NULL, elementId = NULL)
## Not run: 
print(cf)

## End(Not run)

Customizes appearance of condformat object

Description

This is only used on LaTeX output.

Usage

theme_kable(x, ...)

Arguments

See Also

knitr::kable()

Examples

data(iris)
cf <- condformat(head(iris)) |>
  theme_kable(booktabs = TRUE, caption = "My Caption")
## Not run: 
print(cf)

## End(Not run)