Skip to main content

Host CSS and Table Layout

This page defines the compatibility contract between Widgemo table rendering and host-application CSS.

Baseline Rendering Contract​

When a host does not apply broad global table selectors, Widgemo table rendering follows core defaults.

AreaContract
Borders and header stylingDriven by widgemo-core styles and mode config
Row stripingDriven by alternatingRows and row tokens
Density and spacingDriven by core defaults plus responsive mode behavior
Table layout modetraditional uses fixed table layout; rich-cells uses auto table layout
Width strategyRuntime table uses width: max-content with min-width: 100%
Overflow regionInternal scroll region (.widgemo-table-scroll-region) handles constrained container overflow

Constrained Overflow Contract​

For fixed-size or fill containers, scrolling remains internal to Widgemo's table scroll region.

ConditionExpected behavior
Horizontal overflow onlyoverflow-x is discoverable and usable
Vertical overflow onlyoverflow-y is discoverable and usable
Dual overflowBoth axes remain functionally discoverable and usable
Pagination changesVisible row count changes, but overflow discoverability semantics remain consistent

Overlay Scrollbar Caveat​

Some operating systems auto-hide scrollbar rails based on platform preferences. Visual rail persistence is platform-dependent presentation.

The compatibility requirement is functional discoverability and usable scrolling controls, including transient-rail environments.

Row Striping Contract​

alternatingRows (default true) is the native Widgemo striping control. It applies row striping via backgroundColor using --widgemo-row-alt-bg.

Host CSS can restyle appearance, but Widgemo overflow behavior should remain intact. Striping conflicts usually come from explicit host repaint rules.

High-risk host patterns include:

  • tr:nth-child(...) striping rules
  • hard background rules on td/th
  • cell repaint overlays (for example box-shadow: inset 0 0 0 9999px ...)

If striping appears inconsistent, audit host-level table/tr/td paint rules first.

Grouping Chevron Contrast Contract​

Grouped table header chevrons inherit Widgemo icon color tokens (--widgemo-group-chevron-color -> --widgemo-color-iconColor) and must remain legible in light and dark themes.

Host overrides should preserve control affordance and contrast. Keep overrides scoped and avoid broad global icon/color rules.

Host Global CSS Risk Patterns​

Many host apps include global selectors like the following:

/* Examples of host rules that can alter Widgemo table behavior */
table, th, td { border: 1px solid var(--brand-border); }
table tr:nth-child(even) { background: var(--striped-row); }
table th, table td { padding: 12px; }

These selectors can alter Widgemo semantics by introducing unexpected borders, stripe overrides, and spacing changes.

Mitigation Patterns​

Use scoped mitigations around a Widgemo wrapper class, not global table resets.

Docusaurus and Infima hosts only​

If your host stack is Docusaurus with Infima, scoped variable resets can neutralize markdown table chrome leakage inside Widgemo configuration examples.

/* Docusaurus/Infima-only example */
.my-app-widgemo-scope {
  --ifm-table-border-width: 0;
  --ifm-table-border-color: transparent;
  --ifm-table-background: transparent;
  --ifm-table-stripe-background: transparent;
  --ifm-table-head-background: transparent;
}

Framework-agnostic scoped mitigation​

For non-Infima hosts, restore Widgemo table semantics only within a local scope.

/* Example for any host framework */
.my-app-widgemo-scope .widgemo-table {
  display: table;
  margin-bottom: 0;
}

.my-app-widgemo-scope .widgemo-table-scroll-region {
  overflow-x: auto;
}

.my-app-widgemo-scope .widgemo-table > :not(caption) > * > * {
  border: 0;
}

Implementation notes:

  • Keep mitigations scoped to a Widgemo wrapper class.
  • Do not apply these mitigations as global table rules.
  • Do not add density tuning unless you intentionally want a non-default look.

Deterministic column widths​

If host CSS and content variability produce inconsistent column distribution, define explicit field.width values.

fields: [
  { key: 'name', label: 'Name', width: '220px' },
  { key: 'status', label: 'Status', width: '140px' },
  { key: 'owner', label: 'Owner' },
]

Use field.width when:

  • Key columns must remain stable across pages and breakpoints.
  • Content length differences cause noticeable width drift.
  • You need deterministic alignment with external UI elements.

See Also​