Custom styling of the dataframe (#10647)

* changes

* add changeset

* revert

* done

* add changeset

* changes

* notebook

* documentation

* guide

* guide

---------

Co-authored-by: gradio-pr-bot <gradio-pr-bot@users.noreply.github.com>

.changeset/afraid-flowers-win.md

@@ -0,0 +1,5 @@
+---
+"gradio": minor
+---
+
+feat:Custom styling of the dataframe

demo/dataframe_custom_styling/run.ipynb

@@ -0,0 +1 @@
+{"cells": [{"cell_type": "markdown", "id": "302934307671667531413257853548643485645", "metadata": {}, "source": ["# Gradio Demo: dataframe_custom_styling"]}, {"cell_type": "code", "execution_count": null, "id": "272996653310673477252411125948039410165", "metadata": {}, "outputs": [], "source": ["!pip install -q gradio "]}, {"cell_type": "code", "execution_count": null, "id": "288918539441861185822528903084949547379", "metadata": {}, "outputs": [], "source": ["import gradio as gr\n", "\n", "data = [\n", "    [\"DeepSeek Coder\", 79.3],\n", "    [\"Llama 3.3\", 68.9],\n", "    [\"Qwen 2.5\", 61.9],\n", "    [\"Gemma 2\", 59.5],\n", "    [\"GPT 2\", 18.3],\n", "]\n", "\n", "headers = [\"Model\", \"% Correct (LeetCode Hard)\"]\n", "\n", "def get_styling(values):\n", "    return [[\"\", f\"background: linear-gradient(90deg, rgba(220, 242, 220) {row[1]}%, transparent {row[1]}%)\"] for row in values]\n", "\n", "def get_display_value(values):\n", "    display_values = []\n", "    medals = [\"\ud83e\udd47\", \"\ud83e\udd48\", \"\ud83e\udd49\"]\n", "    for i, row in enumerate(values):\n", "        if i < 3:\n", "            display_values.append([f\"{medals[i]} {row[0]}\", row[1]])\n", "        else:\n", "            display_values.append([row[0], row[1]])\n", "    return display_values\n", "\n", "styling = get_styling(data)\n", "display_value = get_display_value(data)\n", "\n", "\n", "value = {\n", "    \"data\": data,\n", "    \"headers\": headers,\n", "    \"metadata\": {\n", "        \"styling\": styling,\n", "        \"display_value\": display_value,\n", "    },\n", "}\n", "\n", "with gr.Blocks() as demo:\n", "    gr.Dataframe(value, show_search=\"search\")\n", "\n", "if __name__ == \"__main__\":\n", "    demo.launch()\n"]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}

demo/dataframe_custom_styling/run.py

@@ -0,0 +1,43 @@
+import gradio as gr
+
+data = [
+    ["DeepSeek Coder", 79.3],
+    ["Llama 3.3", 68.9],
+    ["Qwen 2.5", 61.9],
+    ["Gemma 2", 59.5],
+    ["GPT 2", 18.3],
+]
+
+headers = ["Model", "% Correct (LeetCode Hard)"]
+
+def get_styling(values):
+    return [["", f"background: linear-gradient(90deg, rgba(220, 242, 220) {row[1]}%, transparent {row[1]}%)"] for row in values]
+
+def get_display_value(values):
+    display_values = []
+    medals = ["🥇", "🥈", "🥉"]
+    for i, row in enumerate(values):
+        if i < 3:
+            display_values.append([f"{medals[i]} {row[0]}", row[1]])
+        else:
+            display_values.append([row[0], row[1]])
+    return display_values
+
+styling = get_styling(data)
+display_value = get_display_value(data)
+
+
+value = {
+    "data": data,
+    "headers": headers,
+    "metadata": {
+        "styling": styling,
+        "display_value": display_value,
+    },
+}
+
+with gr.Blocks() as demo:
+    gr.Dataframe(value, show_search="search")
+
+if __name__ == "__main__":
+    demo.launch()

gradio/components/dataframe.py

@@ -382,6 +382,8 @@ class Dataframe(Component):
             return Dataframe.__extract_metadata(
                 value, getattr(value, "hidden_columns", [])
             )
+        elif isinstance(value, dict):
+            return value.get("metadata", None)
         return None
 
     def postprocess(

guides/10_other-tutorials/styling-the-gradio-dataframe.md

@@ -4,11 +4,11 @@ Tags: DATAFRAME, STYLE, COLOR
 
 ## Introduction
 
-Data visualization is a crucial aspect of data analysis and machine learning. The Gradio `DataFrame` component is a popular way to display tabular data (particularly data in the form of a `pandas` `DataFrame` object) within a web application. 
+Data visualization is a crucial aspect of data analysis and machine learning. The Gradio `DataFrame` component is a popular way to display tabular data within a web application. 
+
+But what if you want to stylize the table of data? What if you want to add background colors, partially highlight cells, or change the display precision of numbers? This Guide is for you!
 
-This post will explore the recent enhancements in Gradio that allow users to integrate the styling options of pandas, e.g. adding colors to the DataFrame component, or setting the display precision of numbers. 
 
-![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/df-highlight.png)
 
 Let's dive in!
 
@@ -16,7 +16,7 @@ Let's dive in!
 You can [read the Guide to Blocks first](https://gradio.app/blocks-and-event-listeners) if you are not already familiar with it. Also please make sure you are using the **latest version** version of Gradio: `pip install --upgrade gradio`.
 
 
-## Overview
+## The Pandas `Styler`
 
 The Gradio `DataFrame` component now supports values of the type `Styler` from the `pandas` class. This allows us to reuse the rich existing API and documentation of the `Styler` class instead of inventing a new style format on our own. Here's a complete example of how it looks:
 
@@ -49,7 +49,7 @@ To read more about the Styler object, read the official `pandas` documentation a
 
 Below, we'll explore a few examples:
 
-## Highlighting Cells
+### Highlighting Cells
 
 Ok, so let's revisit the previous example. We start by creating a `pd.DataFrame` object and then highlight the highest value in each row with a light green color:
 
@@ -84,7 +84,7 @@ Here's how it looks:
 
 ![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/df-highlight.png)
 
-## Font Colors
+### Font Colors
 
 Apart from highlighting cells, you might want to color specific text within the cells. Here's how you can change text colors for certain columns:
 
@@ -122,7 +122,7 @@ In this script, we define a custom function highlight_cols that changes the text
 
 ![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/df-color.png)
 
-## Display Precision 
+### Display Precision 
 
 Sometimes, the data you are dealing with might have long floating numbers, and you may want to display only a fixed number of decimals for simplicity. The pandas Styler object allows you to format the precision of numbers displayed. Here's how you can do this:
 
@@ -152,9 +152,24 @@ In this script, the format method of the Styler object is used to set the precis
 ![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/df-precision.png)
 
 
+
+## Custom Styling
+
+So far, we've been restricting ourselves to styling that is supported by the Pandas `Styler` class. But what if you want to create custom styles like partially highlighting cells based on their values:
+
+![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/gradio-guides/dataframe_custom_styling.png)
+
+
+This isn't possible with `Styler`, but you can do this by creating your own **`styling`** array, which is a 2D array the same size and shape as your data. Each element in this list should be a CSS style string (e.g. `"background-color: green"`) that applies to the `<td>` element containing the cell value (or an empty string if no custom CSS should be applied). Similarly, you can create a **`display_value`** array which controls the value that is displayed in each cell (which can be different the underlying value which is the one that is used for searching/sorting).
+
+Here's the complete code for how to can use custom styling with `gr.Dataframe` as in the screenshot above:
+
+$code_dataframe_custom_styling
+
+
 ## Note about Interactivity
 
-One thing to keep in mind is that the gradio `DataFrame` component only accepts `Styler` objects when it is non-interactive (i.e. in "static" mode). If the `DataFrame` component is interactive, then the styling information is ignored and instead the raw table values are shown instead. 
+One thing to keep in mind is that the gradio `DataFrame` component only accepts custom styling objects when it is non-interactive (i.e. in "static" mode). If the `DataFrame` component is interactive, then the styling information is ignored and instead the raw table values are shown instead. 
 
 The `DataFrame` component is by default non-interactive, unless it is used as an input to an event. In which case, you can force the component to be non-interactive by setting the `interactive` prop like this: