Skip to content
Gravity Tables
All documentation

Reference

Styling and customization

CSS overrides, child-theme template overrides, and the recommended approach to brand Gravity Tables to match your site.

Gravity Tables ships clean default styling that works on most themes out of the box. When you need to customize, three tiers of intervention are available:

  1. CSS variables, re-tint the existing design without touching layout
  2. Custom CSS, override specific selectors via your child theme stylesheet
  3. Template overrides, replace the rendered HTML wholesale via child-theme files

Pick the lowest tier that gets you the result.

Tier 1: CSS variables#

The plugin exposes CSS custom properties on :root. Override them in your theme to re-tint colors, borders, and spacing without writing a single new selector.

/* In your child theme's style.css or a custom CSS plugin */
:root {
  --gt-color-text: #1a1a1a;
  --gt-color-bg: #fafafa;
  --gt-color-border: #e5e5e5;
  --gt-color-link: #0066cc;
  --gt-color-link-hover: #004499;
  --gt-color-status-active: #16a34a;
  --gt-color-status-trial: #d97706;
  --gt-color-status-cancelled: #dc2626;

  --gt-font-family: 'Inter', system-ui, sans-serif;
  --gt-font-size-base: 0.95rem;
  --gt-font-size-small: 0.825rem;

  --gt-radius: 8px;
  --gt-cell-padding-x: 1rem;
  --gt-cell-padding-y: 0.625rem;
  --gt-row-stripe: rgba(0,0,0,0.02);
  --gt-row-hover: rgba(0,0,0,0.04);
}

That’s enough for 80% of branding asks. You can match the host theme’s typography, brand colour, and corner radius without writing specific selectors.

Dark mode#

If the host theme has a dark mode, scope variable overrides to its dark-mode selector:

[data-theme="dark"] :root,
.dark-mode :root {
  --gt-color-text: #e5e5e5;
  --gt-color-bg: #1a1a1a;
  --gt-color-border: #333;
  --gt-row-stripe: rgba(255,255,255,0.04);
  --gt-row-hover: rgba(255,255,255,0.08);
}

The plugin’s CSS uses these variables consistently, so a single override applies everywhere.

Tier 2: Custom CSS#

For changes the variables don’t cover (specific spacing, layout tweaks, bespoke component look), use targeted selectors.

Stable class names#

These class names are part of the public API and won’t change between minor versions:

.gt-table             , the root <table> element
.gt-toolbar           , toolbar above the table (search, filter chips, export)
.gt-pagination        , pagination row at the bottom
.gt-cell              , every <td>
.gt-cell--editing     , modifier when a cell is in edit mode
.gt-cell--editable    , modifier on cells that allow_edit configured
.gt-row               , every <tr>
.gt-row--header       , modifier on the <thead> row
.gt-row--totals       , modifier on the totals row in <tfoot>
.gt-row--editing      , modifier when any cell in the row is editing
.gt-status            , status pill (Active / Trial / Cancelled)
.gt-status--active    , status modifier
.gt-status--trial     , status modifier
.gt-status--cancelled , status modifier
.gt-card              , card layout on mobile (≤480px breakpoint)
.gt-empty-state       , empty-table message
.gt-loading           , spinner / loading shimmer

Common overrides#

/* Tighter cell padding on desktop */
.gt-table .gt-cell {
  padding: 0.5rem 0.75rem;
}

/* Brand-colored header row */
.gt-table .gt-row--header {
  background: #0066cc;
  color: white;
}

/* Soft hover state */
.gt-table .gt-row:hover {
  background: rgba(0, 102, 204, 0.04);
  transform: translateY(-1px);
  transition: all 150ms ease;
}

/* Custom status pill colors per category */
.gt-status--vip {
  background: linear-gradient(135deg, #f59e0b, #f97316);
  color: white;
}

Per-table overrides#

Each rendered table has the table ID as a data- attribute. Use it for targeted overrides:

[data-gt-table="42"] .gt-row {
  border-color: #0066cc;
}

This affects only the table with id="42", the rest of the site is untouched.

Tier 3: Template overrides#

For changes the CSS layer can’t cover (different markup, new wrappers, custom cell renderers), override the rendered template via your child theme.

How template overrides work#

The plugin looks for matching template files in this order:

  1. your-child-theme/gravity-tables/{template}.php
  2. your-parent-theme/gravity-tables/{template}.php
  3. wp-content/plugins/gravity-tables/templates/{template}.php (default)

Copy any template from the plugin’s templates/ folder into your child theme’s gravity-tables/ folder, edit, save. The plugin uses your version on subsequent renders.

Available templates#

table.php           , the root <table> element + toolbar wrapper
toolbar.php         , search, filters, export, add-entry buttons
row-header.php      , the <thead> row
row-data.php        , every data row
cell.php            , individual cell renderer (with type detection)
status-pill.php     , the status badge component
card.php            , mobile card layout
pagination.php      , page nav at the bottom
empty.php           , empty-state message
loading.php         , loading skeleton

Example: custom cell renderer#

Suppose you want phone-number cells to render as click-to-call links. Override cell.php:

<?php
/**
 * Override: gravity-tables/cell.php
 * Adds tel: links to phone-number fields.
 */
$value = $cell['value'] ?? '';
$field = $cell['field'] ?? null;

if ($field && $field['type'] === 'phone') {
    $clean = preg_replace('/[^\d+]/', '', $value);
    printf('<td class="gt-cell"><a href="tel:%s">%s</a></td>',
        esc_attr($clean), esc_html($value));
} else {
    // Fall through to default rendering
    include WP_PLUGIN_DIR . '/gravity-tables/templates/cell.php';
}

Example: branded toolbar#

Override toolbar.php to add a logo above the search:

<?php
/**
 * Override: gravity-tables/toolbar.php
 */
?>
<div class="gt-toolbar gt-toolbar--branded">
    <img src="<?php echo esc_url(get_template_directory_uri() . '/img/logo.svg'); ?>" alt="" class="gt-toolbar__logo">
    <?php include WP_PLUGIN_DIR . '/gravity-tables/templates/toolbar.php'; ?>
</div>

Mixing CSS variables and overrides#

The three tiers compose. A typical production deployment uses:

  • CSS variables for site-wide brand colours
  • Custom CSS for per-table tweaks and one-off layout changes
  • Template overrides for one or two specific cell types (phone, address, status)

Keep template overrides minimal, they’re the highest-maintenance tier. CSS overrides survive plugin updates with zero attention; template overrides need re-testing on every major release.

Performance considerations#

  • CSS overrides are essentially free, the browser applies them inline
  • Per-table overrides via [data-gt-table] selectors don’t affect other tables (good selector scoping)
  • Template overrides cost a tiny PHP include per render, negligible for typical traffic

What you can’t customize#

  • The shortcode parameter shape (intentionally stable across versions)
  • The audit log table schema (used for compliance reporting)
  • The AJAX endpoint structure (versioned /wp-json/gt/v1/)

If you need to extend the shortcode behavior, use the PHP hooks instead of trying to override the shortcode parser.

← All documentation