carbon react grid subgrid layout

---

title: "Carbon React Grid and Subgrid Layouts" type: pattern description: >- Use Carbon Grid and Column spans for responsive layout, and scope generated-grid styling to named component hooks. domain: frontend framework: react tags: [carbon, grid, subgrid, responsive-layout, sass] created: 2026-11-02 updated: 2026-11-02

Pattern

Use Carbon React Grid and Column props to define responsive spans. In this application Carbon CSS renders grid internals such as .cds--subgrid and .cds--css-grid-column. These names describe current output, not a public styling contract. Prefer React breakpoint props and component-owned class hooks. If Sass must target generated grid children, scope it under a named grid or column hook; do not style every descendant of .cds--grid.

Carbon’s default grid has 16 columns at wide breakpoints, 8 at md, and 4 at sm. Set sm, md, lg, xlg, and max span props on Column for the responsive behavior the layout needs. Check Carbon’s component documentation; do not infer a public API from generated CSS class names.

Separate Layout Groups

Keep semantically distinct rows or sections in separate Grids. In the read-only branch of InteriorSubmissionDetailsForm, the six summary fields use .interior-submission-details__summary-grid; retention and criteria content uses .interior-submission-details__details-grid. A width cap for the summary must not also constrain the lower controls.

Field order affects responsive wrapping. Use explicit Column spans and source order to keep related fields together, then inspect the rendered layout at each target width. Span totals alone do not prove that the grouping is readable.

Intrinsic Widths and Browser Checks

Column spans divide available grid space; they do not assign exact intrinsic pixel widths. One browser-verified desktop example supplied for this pattern measured the six fields at about 202/197/206/176/160/166 px, with 16 px gaps, for roughly 1,187 px overall. Matching those measurements required a scoped cap/width treatment on the summary grid and its column hooks. In a card with about 871 px of content width, the row wrapped into two three-field rows with columns around 280 px and no horizontal overflow. These figures describe that example, not reusable constants. No stylesheet path or commit for its cap rules was supplied.

The geometry example is separate from commit bce28783. That commit adds the summary grid and column hooks in the component, but its index.scss does not contain the cap/width rules, and its unit tests do not assert viewport geometry. Treat the values as browser-measured evidence for the method, not behavior guaranteed by the commit.

When validating a real screen:

• Measure computed bounding rectangles at wide and constrained content widths.
• Account for Carbon grid gutters and subgrid behavior in the measurements.
• Check horizontal scroll and overflow, including card padding and any sidebar.
• Measure the form’s content area; a 1280 px viewport does not give the form 1280 px when a sidebar or card padding reduces the available width.
• Confirm xlg and max rules do not force equal spans against the React props.

Scoped Styling Example

The component’s read-only summary columns combine explicit spans with named hooks:

<Grid className="interior-submission-details__summary-grid">
  <Column
    className="interior-submission-details__summary-column"
    max={3}
    xlg={3}
    lg={3}
    md={4}
    sm={4}
  >
    <ReadonlyInput label="Primary logging complete">
      {values.primaryLoggingCompleteDate}
    </ReadonlyInput>
  </Column>
</Grid>

Avoid broad selectors or breakpoint rules that restate spans on generic Carbon columns. Such overrides can replace React-generated responsive spans or affect unrelated grids. Do not use xlg/max rules to make columns equal when the component props specify different spans. If Sass must style generated children, nested selectors under .interior-submission-details__summary-grid or .interior-submission-details__details-grid keep the scope local.

Sass and Provenance

Follow the project’s Carbon Sass @use and token conventions; do not invent a palette. The committed stylesheet uses Carbon spacing, border-radius, and typography modules, project page-shell, and scoped .interior-submission-details__details-grid rules. Read that source for its exact styles rather than copying the whole stylesheet into another feature.

Provenance: commit bce28783 (feat(#1239): add InteriorSubmissionDetailsForm component with styles and tests):

• frontend/src/components/waste/ReportingUnits/InteriorSubmissionDetailsForm/index.tsx — Grid/Column props, summary/detail hooks, and field order.
• frontend/src/components/waste/ReportingUnits/InteriorSubmissionDetailsForm/index.scss — scoped details-grid, card, and Carbon token styling.
• frontend/src/components/waste/ReportingUnits/InteriorSubmissionDetailsForm/index.unit.test.tsx — field rendering, conditional retention, read-only values, and actions; not viewport geometry.

Carbon references:

• Carbon 2x Grid breakpoints
• React Grid component documentation