Matrix

Patrick Rekieta

2026-02-04

Build charts using the new matrix system added in Echarts v6. echarts4r now comes with a highly customisable matrix coordinate system, which in some methods is easier to use than the previous grid functionality. Build custom tables using the new matrix functions. Note that as of Echarts4r v0.5.0, timelines are not currently supported with matrix functions.

Matrix

To get started with using a matrix, there are a few options you can use. The two starting options consist of e_matrix and e_matrix_raw. You can learn more about the matrix system using the official documentation for additional details. It is worth mentioning that not all series will support the matrix system and some require the matrix to be used in combination with the already existing grid system. See the table at the bottom of the page for additional details.

Now let’s get started with building some matrix charts! e_matrix will take two columns that contain your x and y groupings and will plot the unique combinations in a table style format. There is no need to use group_by with the matrix functions.

df <- data.frame("Class" = rep(c("Class1", "Class2", "Class3"),each = 3),
"Grade" = c("Grade1","Grade2", "Grade3"))

df |> 
  e_charts() |> 
  e_matrix(xAxis = "Class", yAxis = "Grade")

If we only want to create the table with no additional headers or column names, we can instead use the e_matrix_raw to generate the matrix. This will be especially useful when adding new charts directly to the matrix later on. When using e_matrix_raw you will need to specify how many columns and rows you want in your table.

e_matrix_raw(rows = 3, cols = 3, backgroundStyle=list(borderWidth=0))

All tables are fully customizable through the supported css options found here. We can use these options to fully remove the lines of the table leaving an blank matrix if desired.

Format matrix

There are a few other ways that we can customize our matrix table to reach our desired output. First we can take our initial example from e_matrix and add some text to the corner cell of the headers. To do this, we will use e_matrix_corner to access that corner cell. Documentation for the corner cell can be found here.

df |> 
  e_charts() |> 
  e_matrix(xAxis = "Class", yAxis = "Grade") |> 
  e_matrix_corner(value = "Schools")

Now we can add additional levels to our headers. This is done using e_matrix_parent to add new levels. To use this function, we will give it our new text value. We also need to specify which existing headers will be children of this new header parent. As you mess around with e_matrix_parent you may notice that additional cells are being generated for the corner of the table. In e_matrix_corner we can specify where we want that corner value to go using the coord attribute. As of Echarts4r v0.5.0, there is no way to add new children to the headers.

df |> e_charts() |> 
  e_matrix(xAxis = "Class", yAxis = "Grade") |>
  e_matrix_parent(value = "Primary", children = c("Class1", "Class2")) |>
  e_matrix_parent(value = "High", children = "Class3") |>
  e_matrix_parent(value = "ALL", children = c("Primary", "High")) |>
  e_matrix_corner(value = "Schools", coord = c(-1,-2))

When working with the matrix functions, it is important to remember that the coordinate system is formatted as [col_number, row_number]. Additionally, row and column counting starts at 0. If we need to make additional changes to how our headers look, we can easily access the formatting options using e_format_matrix_axis. Documentation for the axis options can be found here.

df |> 
  e_charts() |> 
  e_matrix(xAxis = "Class", yAxis = "Grade") |> 
  e_matrix_corner(value = "Schools") |>
  e_matrix_parent(value = "Primary", children = c("Class1", "Class2")) |>
  e_format_matrix_axis(axis = "y", label = list(color = "red")) |>
  e_format_matrix_axis(axis = "x", itemStyle = list(color = "#999"), label = list(fontSize = 25))

Adding charts

Table Style

Now that we have built our table, we can start adding some charts to each cell. In order to do this, we will use e_matrix_addChart. This will allows us to pre-build an Echart and add it to a specific cell (Note: Each Echart will need a unique ID when added to the matrix).

Let’s get building! First we can build some basic charts that we want to add.

echart1 <- iris |>
  group_by(Species) |>
  e_charts(Sepal.Length) |>
  e_line(Sepal.Width) |>
  e_tooltip(trigger = "axis")

echart2 <- mtcars |>
  head() |>
  tibble::rownames_to_column("model") |>
  e_charts(model) |>
  e_pie(carb)

echart3 <- mtcars |>
  tibble::rownames_to_column("model") |>
  mutate(total = mpg + qsec) |>
  arrange(desc(total)) |>
  e_charts(model) |>
  e_bar(mpg, stack = "grp") |>
  e_bar(qsec, stack = "grp") |>
  e_tooltip(trigger = "item")

echart4 <- iris |>
  e_charts() |>
  e_boxplot(Sepal.Length) |>
  e_tooltip()


df |> 
  e_charts() |> 
  e_matrix(xAxis = "Class", yAxis = "Grade") |> 
  e_matrix_corner(value = "Schools") |>
  e_matrix_addChart(chart = echart1, id = "Chart1", coord = c(0,0)) |>
  e_matrix_addChart(chart = echart2, id = "Chart2", coord = c(1,1), legend = FALSE) |>
  e_matrix_addChart(chart = echart3, id = "Chart3", coord = c(2,1))

Dashboard style

In addition to filling single cells of the matrix, we can also fill multiple / merge multiple cells. To do this we use the format [(col_start, col_end), (row_start, row_end)]. This functionality can be used to create dashboard style presentations of multiple charts.

e_matrix_raw(3,3, body = list(itemStyle = list(borderWidth = 0))) |>
  e_matrix_addChart(echart1, id = "Chart1", coord = list(c(0,2),0)) |>
  e_matrix_addChart(echart3, id = "Chart2", coord = list(c(1,2),c(1,2))) |>
  e_matrix_addChart(echart4, id = "Chart3", coord = list(0,c(1,2)), legend = FALSE) |>
  e_tooltip()

geoFacet style

Inspired by the geofacet package for ggplot, you can now use the matrix system to generate tables that are shaped like a specified grid. This functionality supports custom grids or a string containing the name of an existing geofacet grid. You can find the pre-built grids here.

df <- data.frame(group = rep(letters[1:6], each = 20),
  date = seq(from = as.Date("2025-01-01"),
             to = as.Date("2025-01-20"), by = "day"),
  temp = sample(c(10:20), size = 60, replace = TRUE))

grid <- data.frame(name = unique(df$group), row = c(1:6), col = c(1:6))

df |>
  group_by(group) |>
  e_chart(date) |>
  e_line(temp, symbol = "none") |>
  e_x_axis(splitNumber = 2) |>
  e_y_axis(splitNumber = 2) |>
  e_geoFacet(legend = FALSE,
             grid = grid,
             margin_trbl = c("t"="25%"),
             left = "5%",
             width = "90%") |>
  e_title(text = "Group Temps") |>
  e_tooltip(trigger = "axis")

We can also add titles to each graph using e_title_matrix.

df |>
  group_by(group) |>
  e_chart(date) |>
  e_line(temp, symbol = "none") |>
  e_x_axis(splitNumber = 2) |>
  e_y_axis(splitNumber = 2) |>
  e_geoFacet(legend = FALSE,
             grid = grid,
             margin_trbl = c("t"="25%"),
             left = "5%",
             width = "90%") |>
  e_title(text = "Group Temps") |>
  e_tooltip(trigger = "axis") |>
  e_title_matrix()

Supported Series

Heatmap Chart

df <- data.frame("Class" = rep(c("Class1", "Class2", "Class3"),each = 3),
                   "Grade" = c("Grade1","Grade2", "Grade3"),
                  "A" = sample(1:10, 9),
                  "B" = sample(1:10,9),
                  "C" = sample(1:10,9))

df |> e_chart() |>
 e_matrix(xAxis = "Class", yAxis = "Grade") |>
 e_heatmap(A, coord_system = "matrix") |>
 e_labels(position = "inside",
          formatter = htmlwidgets::JS(
            'function(params){return(params.value[2]);}'),
          fontWeight = "bold") |>
 e_visual_map(A, inRange = list(color = c("#bf444c", "#d88273", "#f6efa6")))

Pie Chart

df |> e_chart() |>
 e_matrix(xAxis = "Class", yAxis = "Grade") |>
 e_pie_(serie = c("A","B","C"), coord_system = "matrix", label = list(show = FALSE))

Scatter Chart

df |> e_chart() |>
 e_matrix(xAxis = "Class", yAxis = "Grade") |>
 e_scatter(A, coord_system = "matrix", symbolSize = 20) |>
 e_labels(position = "inside",
          formatter = htmlwidgets::JS(
           'function(params){return(params.value[2]);}'),
          color = "black",
          fontWeight = "bold") |>
  e_visual_map(A, inRange = list(symbolSize = c(20,50)))

Matrix Support

	no coord sys	grid (cartesian2d)	polar	geo	singleAxis	radar	parallel	calendar	matrix
grid (cartesian2d)	✅	❌	❌	❌	❌	❌	❌	✅	✅
polar	✅	❌	❌	❌	❌	❌	❌	✅	✅
geo	✅	❌	❌	❌	❌	❌	❌	✅	✅
singleAxis	✅	❌	❌	❌	❌	❌	❌	✅	✅
calendar	✅	❌	❌	❌	❌	❌	❌	❌	❌
matrix	✅	❌	❌	❌	❌	❌	❌	❌	❌
series-line	❌	✅	✅	❌	❌	❌	❌	❌ (✅ if via another coord sys like grid)	❌ (✅ if via another coord sys like grid)
series-bar	❌	✅	✅	❌	❌	❌	❌	❌ (✅ if via another coord sys like grid)	❌ (✅ if via another coord sys like grid)
series-pie	✅	✅	✅	✅	✅	❌	❌	✅	✅
series-scatter	❌	✅	✅	✅	✅	❌	❌	✅	✅
series-effectScatter	❌	✅	✅	✅	✅	❌	❌	✅	✅
series-radar	❌	❌	❌	❌	❌	✅	❌	❌ (✅ if via radar coord sys)	❌ (✅ if via radar coord sys)
series-tree	✅	❌	❌	❌	❌	❌	❌	✅	✅
series-treemap	✅	❌	❌	❌	❌	❌	❌	✅	✅
series-sunburst	✅	❌	❌	❌	❌	❌	❌	✅	✅
series-boxplot	❌	✅	❌	❌	❌	❌	❌	❌ (✅ if via another coord sys like grid)	❌ (✅ if via another coord sys like grid)
series-candlestick	❌	✅	❌	❌	❌	❌	❌	❌ (✅ if via another coord sys like grid)	❌ (✅ if via another coord sys like grid)
series-heatmap	❌	✅	❌	✅	❌	❌	❌	✅	✅
series-map	✅ (create a geo coord sys exclusively)	❌	❌	✅	❌	❌	❌	✅	✅
series-parallel	❌	❌	❌	❌	❌	❌	✅	❌ (✅ if via parallel coord sys)	❌ (✅ if via parallel coord sys)
series-lines	❌	✅	✅	✅	✅	❌	❌	❌ (✅ if via another coord sys like geo)	❌ (✅ if via another coord sys like geo)
series-graph	✅ (create a “view” coord sys exclusively)	✅	✅	✅	❌	❌	❌	✅	✅
series-sankey	✅	❌	❌	❌	❌	❌	❌	✅	✅
series-funnel	✅	❌	❌	❌	❌	❌	❌	✅	✅
series-gauge	✅	❌	❌	❌	❌	❌	❌	✅	✅
series-pictorialBar	❌	✅	✅	❌	❌	❌	❌	❌ (✅ if via another coord sys like grid)	❌ (✅ if via another coord sys like grid)
series-themeRiver	❌	❌	❌	❌	✅	❌	❌	❌ (✅ if via another coord sys like singleAxis)	❌ (✅ if via another coord sys like singleAxis)
series-chord	✅	✅	✅	✅	✅	❌	❌	✅	✅
title	✅	❌	❌	❌	❌	❌	❌	✅	✅
legend	✅	❌	❌	❌	❌	❌	❌	✅	✅
dataZoom	✅	❌	❌	❌	❌	❌	❌	✅	✅
visualMap	✅	❌	❌	❌	❌	❌	❌	✅	✅
toolbox	✅	❌	❌	❌	❌	❌	❌	✅	✅
timeline	✅	❌	❌	❌	❌	❌	❌	✅	✅
thumbnail	✅	❌	❌	❌	❌	❌	❌	✅	✅