Documentation

Custom Theme

Simple Table offers two complementary ways to customize your table's appearance: CSS-based theming for colors and visual styling, and the customTheme prop for layout dimensions that affect virtualization calculations.

Two Types of Customization

  • CSS Theming - Use CSS variables to customize colors, fonts, and visual styles. Perfect for matching your design system.
  • customTheme Prop - Configure layout dimensions (heights, widths, spacing) that affect virtualization calculations. These cannot be styled through CSS alone.

customTheme Prop: Layout Dimensions

The customTheme prop allows you to configure layout dimensions that are critical for the table's virtualization engine. These values determine how the table calculates scroll positions, visible rows, and layout measurements.

Why These Can't Be CSS-Only

Simple Table uses virtualization to efficiently render large datasets by only rendering visible rows. To calculate which rows are visible and where to position them, the table needs to know exact pixel dimensions before rendering. CSS values can't be read synchronously during render, so these dimensions must be provided as props.

customTheme Properties

PropertyRequiredDescriptionExample
rowHeight
number
Optional
Height of table rows in pixels. This value is used for virtualization calculations and cannot be styled through CSS. If not specified, uses the default value of 40px.
headerHeight
number
Optional
Height of the table header in pixels. This value is used for virtualization calculations and cannot be styled through CSS. If not specified, uses the default value of 40px.
footerHeight
number
Optional
Height of the table footer in pixels. This value is used for virtualization calculations and cannot be styled through CSS. If not specified, uses the default value of 50px.
rowSeparatorWidth
number
Optional
Width of separators between rows in pixels. This value affects virtualization calculations and cannot be styled through CSS. If not specified, uses the default value of 1px.
borderWidth
number
Optional
General border width in pixels (e.g., table borders, header borders). This value affects layout calculations and cannot be styled through CSS. If not specified, uses the default value of 1px.
pinnedBorderWidth
number
Optional
Width of borders for pinned columns in pixels. This value affects layout calculations for pinned columns and cannot be styled through CSS. If not specified, uses the default value of 2px.
nestedGridBorderWidth
number
Optional
Border width for nested grid tables (top + bottom) in pixels. This value affects nested table layout calculations and cannot be styled through CSS. If not specified, uses the default value of 2px.
nestedGridPaddingTop
number
Optional
Top padding for nested grids in pixels. This value affects nested table layout calculations and cannot be styled through CSS. If not specified, uses the default value of 8px.
nestedGridPaddingBottom
number
Optional
Bottom padding for nested grids in pixels. This value affects nested table layout calculations and cannot be styled through CSS. If not specified, uses the default value of 8px.
nestedGridPaddingLeft
number
Optional
Left padding for nested grids in pixels. This value affects nested table layout calculations and cannot be styled through CSS. If not specified, uses the default value of 16px.
nestedGridPaddingRight
number
Optional
Right padding for nested grids in pixels. This value affects nested table layout calculations and cannot be styled through CSS. If not specified, uses the default value of 16px.
nestedGridMaxHeight
number
Optional
Maximum height for nested grids in pixels. This value controls how tall nested tables can grow before scrolling. If not specified, nested grids will grow to fit their content.
selectionColumnWidth
number
Optional
Width of the row selection checkbox column in pixels. This value affects layout calculations and cannot be styled through CSS. If not specified, uses the default value of 40px.

Common Use Cases

  • Compact tables - Reduce rowHeight to 32px for dense data displays
  • Spacious layouts - Increase rowHeight to 56px or more for better readability
  • Nested tables - Configure nestedGridMaxHeight to control how tall nested grids can grow
  • Custom borders - Adjust border widths to match your design system

For a complete reference of all customTheme properties, see the API Reference.

CSS Theming: Colors and Visual Styling

Beyond the built-in themes, Simple Table allows you to create completely custom themes using CSS variables. By defining your own theme with custom colors, spacing, and typography, you can perfectly match your application's design system.

StackBlitz

Creating a Custom CSS Theme

To create a custom CSS theme for Simple Table, follow these steps:

  1. Create a CSS file with your theme variables using the .theme-custom class
  2. Import the CSS file into your application
  3. Apply the theme by passing theme="custom" to the SimpleTable component

CSS Theme Configuration

PropertyRequiredDescriptionExample
theme
enum
Optional
Set to "custom" to apply your custom CSS theme. Requires a corresponding CSS file with .theme-custom class and CSS variables.

Theme Variable Tips

  • Use the .theme-custom class to define your custom theme
  • Define CSS variables with the --st- prefix
  • Customize colors, spacing, fonts, and transitions
  • Use direct hex values or color variables for consistent styling
  • Test your theme with different features like column resizing and cell selection

CSS Variables Example

Here are the CSS variables used to create the custom theme in the demo above:

React TSXCustomThemeDemo.tsx
1import {SimpleTable} from "@simple-table/react";import type { Theme } from "@simple-table/react";
2import { customThemeConfig } from "./custom-theme.demo-data";
3import "@simple-table/react/styles.css";
4import "./custom-theme.css";
5

6const CustomThemeDemo = ({
7  height = "400px",
8  theme,
9}: {
10  height?: string | number;
11  theme?: Theme;
12}) => {
13  return (
14    <SimpleTable
15      columns={customThemeConfig.headers}
16      rows={customThemeConfig.rows}
17      theme={theme ?? "custom"}
18      customTheme={customThemeConfig.tableProps.customTheme}
19      columnResizing
20      selectableCells
21      height={height}
22    />
23  );
24};
25

26export default CustomThemeDemo;
27

28

29// custom-theme.css
30.theme-custom {
31  --st-border-radius: 8px;
32  --st-cell-padding: 12px;
33

34  --st-spacing-small: 6px;
35  --st-spacing-medium: 10px;
36

37  --st-scrollbar-bg-color: #f5f5f4;
38  --st-scrollbar-thumb-color: #8b5cf6;
39

40  --st-border-color: #e7e5e4;
41  --st-odd-row-background-color: #fffbeb;
42  --st-even-row-background-color: #fef3c7;
43  --st-odd-column-background-color: #fffbeb;
44  --st-even-column-background-color: var(--st-white);
45  --st-hover-row-background-color: #fde68a;
46  --st-selected-row-background-color: #f5f3ff;
47  --st-header-background-color: #7c3aed;
48  --st-header-label-color: var(--st-white);
49  --st-header-icon-color: var(--st-white);
50  --st-dragging-background-color: #f5f3ff;
51  --st-selected-cell-background-color: #f5f3ff;
52  --st-selected-first-cell-background-color: #ede9fe;
53  --st-footer-background-color: #f5f5f4;
54  --st-cell-color: #44403c;
55  --st-cell-odd-row-color: #44403c;
56  --st-edit-cell-shadow: 0 4px 6px -1px rgba(124, 58, 237, 0.1),
57    0 2px 4px -1px rgba(124, 58, 237, 0.06);
58  --st-selected-cell-color: #5b21b6;
59  --st-selected-first-cell-color: #5b21b6;
60  --st-resize-handle-color: #a78bfa;
61  --st-resize-handle-selected-color: var(--st-white);
62  --st-separator-border-color: #e7e5e4;
63  --st-last-group-row-separator-border-color: #d6d3d1;
64

65  --st-selected-border-color: #8b5cf6;
66  --st-editable-cell-focus-border-color: #8b5cf6;
67

68  --st-checkbox-checked-background-color: #8b5cf6;
69  --st-checkbox-checked-border-color: #7c3aed;
70  --st-column-editor-background-color: var(--st-white);
71  --st-column-editor-popout-background-color: var(--st-white);
72  --st-button-hover-background-color: #f5f3ff;
73  --st-button-active-background-color: #7c3aed;
74  --st-cell-flash-color: #ddd6fe;
75  --st-copy-flash-color: #8b5cf6;
76  --st-warning-flash-color: var(--st-red-300);
77

78  --st-header-selected-background-color: #6d28d9;
79  --st-header-selected-label-color: var(--st-white);
80  --st-header-selected-icon-color: var(--st-white);
81

82  --st-header-highlight-indicator-color: #d6d3d1;
83  --st-selection-highlight-indicator-color: #d6d3d1;
84

85  --st-next-prev-btn-color: #57534e;
86  --st-next-prev-btn-disabled-color: #a8a29e;
87

88  --st-page-btn-color: #57534e;
89  --st-page-btn-hover-background-color: #fef3c7;
90

91  --st-column-editor-text-color: #78716c;
92

93  --st-checkbox-border-color: #d6d3d1;
94

95  --st-dropdown-group-label-color: #78716c;
96

97  --st-datepicker-weekday-color: #78716c;
98  --st-datepicker-other-month-color: #a8a29e;
99

100  --st-filter-button-disabled-background-color: #d6d3d1;
101  --st-filter-button-disabled-text-color: #78716c;
102

103  --st-sub-header-background-color: #8b5cf6;
104  --st-sub-cell-background-color: #fef8dc;
105  --st-sub-cell-hover-background-color: #fef3c7;
106  --st-dragging-sub-header-background-color: #c4b5fd;
107  --st-selected-sub-cell-background-color: #ede9fe;
108  --st-selected-sub-cell-color: #4c1d95;
109

110  --st-chart-color: #8b5cf6;
111  --st-chart-fill-color: #c4b5fd;
112

113  --st-drag-separator-color: #8b5cf6;
114}
115

116.theme-custom .st-header-label {
117  font-weight: 600 !important;
118  letter-spacing: 0.025em !important;
119}
120

Combining Both Approaches

You can use both CSS theming and the customTheme prop together for complete control over your table's appearance:

Best Practice

Use CSS variables for all color and visual styling (backgrounds, borders, fonts, shadows), and use the customTheme prop for dimensions that affect layout calculations (heights, widths, spacing). This separation ensures optimal performance and maintainability.

New in v2.4.1: Column Editor Styling

Version 2.4.1 introduces new CSS classes and variables for styling the enhanced column editor with drag-and-drop and search functionality.

New Column Editor CSS Classes

  • .st-column-editor-search-wrapper - Search input container
  • .st-column-editor-search - Search input wrapper
  • .st-column-editor-list - Column list container
  • .st-column-label-container - Column label wrapper
  • .st-drag-icon-container - Drag handle container
  • .st-column-editor-drag-separator - Drag drop indicator line

New CSS Variables:

  • --st-drag-separator-color - Color of the drag drop indicator line (theme-specific)

See the Column Editing documentation for more details on the column editor features.

Sub-Column Styling

Dedicated CSS variables for styling sub-columns (child columns within collapsible column groups). These variables give you fine-grained control over the appearance of nested column structures.

New Sub-Column CSS Variables

  • --st-sub-cell-hover-background-color - Background color when hovering over sub-cells
  • --st-dragging-sub-header-background-color - Background color when dragging sub-headers
  • --st-selected-sub-cell-background-color - Background color for selected sub-cells
  • --st-selected-sub-cell-color - Text color for selected sub-cells

These variables complement the existing sub-column variables:

  • --st-sub-header-background-color - Background color for sub-column headers
  • --st-sub-cell-background-color - Background color for sub-column cells

See the Collapsible Columns documentation for more details on using these variables.