modular-ds-presentational-components

---
name: modular-ds-presentational-components
description: 'Use when: building or evaluating flexible, composable Primer React parts that consumers assemble directly, or deciding whether a pattern is ready to become a config component. Covers structure-first composition, pairing presentational components with behavior hooks, data-component attributes, sub-component export conventions, and when to promote a pattern up the spectrum.'
---

# Modular DS — Presentational Components

Presentational components are styled pieces that consumers compose directly. Primer still owns the styling, accessibility expectations, data attributes, and component contracts for each piece — consumers control layout, ordering, conditional rendering, and content.

The sample below is **illustrative only** — `useList` and the `List` parts don't exist in the repo, and it's shorthand for the shape, not code to copy. Verify any hook you plan to use, per `modular-ds-utilities`.

```tsx
function Example({items}) {
  const [state, actions] = useList({defaultSelected: []})
  return (
    <List>
      {items.map(item => (
        <List.Item key={item.label} onClick={() => actions.toggleSelect(item.label)}>
          <List.ItemLeadingVisual>
            <List.ItemSelection selected={state.selected.has(item.label)} />
          </List.ItemLeadingVisual>
          <List.ItemLabel>{item.label}</List.ItemLabel>
        </List.Item>
      ))}
    </List>
  )
}
```

Shown above with dot-notation for readability — see "Sub-component export conventions" below for the actual RSC-safe export shape to ship.

## When to use presentational components

- The pattern is **emerging** — it's known to exist, but the right high-level config API hasn't stabilized yet.
- Consumers need more flexibility than a config component's props surface can reasonably expose (variants, custom ordering, conditional rendering).

Presentational components are usually the starting point for a new component area — default to building these first, then add behavior through hooks, and only add a config component later once patterns and defaults are established (see `modular-ds-config-components`).

## Behavior via hooks

State and interactions are usually provided separately through a behavior/state hook, letting consumers choose how much behavior to adopt. Keep behavior hooks internal (not part of the public API) unless the requested API or a clear consumer need requires making them public — see `modular-ds-utilities` for hook conventions.

## Composition rules

- Prefer ordinary React children over render props or `React.Children` + `React.cloneElement` for presentational composition. `cloneElement` in particular is fragile and breaks when consumers wrap children. Render props remain a legitimate extension point where a config component genuinely needs them (see `modular-ds-config-components` and `contributor-docs/style.md`) — this is a default, not a prohibition.
- Don't reach for the slots system by default. `useSlots` and `__SLOT__` markers are for the narrow case where a parent must identify a specific child part or extract a child out of the tree — not a general composition mechanism. Prefer plain children first, and only introduce slots when the requested API genuinely needs child extraction. See the `slots` skill for the mechanics if you do.
- Preserve consumer-authored child order. A presentational component should never reorder the children it's given — document the recommended structure instead.
- Use context (`use<Component>Context()`) for ARIA wiring between sub-components — never expose that context to consumers.
- Keep sub-components composable — don't bake one sub-component into another. For example, `Header` should accept `Title` and `CloseButton` as children rather than rendering `CloseButton` internally, so consumers control placement and omission.
- Use existing Primer components where appropriate (e.g. `Button`, `IconButton`, Octicons) instead of re-implementing native elements with custom styling. Where a component needs Primer-owned button semantics, interaction behavior, and reset styling, build on a shared primitive such as `ButtonBase` rather than hand-rolling a button reset in CSS. When you do, don't pass opinionated layout or variant props through to that primitive unless the component's own API exposes the choice, or a concrete design reference requires it — otherwise you're hard-coding an appearance decision the consumer can't reach.
- Use CSS Modules (`.module.css`) with Primer design tokens for styling, and `clsx` for className merging.

## `data-component` attributes

All presentational parts must include `data-component` attributes for stable selectors (testing, agents):

- Root: `data-component="ComponentName"`
- Sub-components: `data-component="ComponentName.PartName"`

`data-component` is owned by Primer as a component identifier — it must never be exposed as a customizable public prop.

Don't stamp `data-component` onto a composed Primer component. An existing component such as `IconButton` sets its own value before spreading incoming props, so passing your own overwrites it, silently removing that component's identifier from the DOM — a breaking change to a stable selector under ADR-023, with no semver signal. Put your identifier on an element your component owns, or build on `ButtonBase` instead. ADR-023 doesn't currently rule on two Primer components claiming one element, so if you hit a case that genuinely needs it, surface it as a gap rather than resolving it inside a component PR.

Note that the `ComponentName.PartName` value and the flat export names above deliberately diverge: consumers write `<ToolbarSeparator>` while the DOM says `Toolbar.Separator`. ADR-023 asks the value to match the React API, and for a component using dot-notation it does. For a new component shipping flat exports it can't, and the dotted value is still the right one — it stays stable if the component later gains a composed object, and it groups the parts. Don't rename either to make them match.

`data-component` is identity, not a styling hook. Never write CSS that selects on it — least of all another component's, which couples your styles to markup that component is free to change. Per ADR-023 (`contributor-docs/adrs/adr-023-stable-selectors-api.md`), the DOM around a `data-component` element — its parent, children, siblings and attributes — is explicitly **not** public API, so a component may target its own parts but never reach into another component's. Values are PascalCase `ComponentName.PartName`, not camelCase. Wrap `data-*` state and ARIA state selectors in `:where()` so those parts add no specificity and don't outrank a base component's reset — see `modular-ds-base-components` for the ADR-021 caveat on this convention.

A `data-*` state attribute must mean the same thing on every part of a component that carries it. If a part needs a derived or inverted value — a separator in a horizontal toolbar being drawn vertically, say — give it a differently-named attribute rather than reusing the parent's under an opposite meaning. These attributes are the stable selector surface, so two parts one DOM level apart disagreeing about what `data-orientation` means is a trap for every consumer who writes a descendant selector.

## Sub-component export conventions

Flat exports (e.g. `DialogRoot`, `DialogHeader`, `DialogTitle`) are the goal for React Server Components compatibility — the `Object.assign` dot-notation pattern breaks in RSC (property access on a client reference returns `undefined`). Follow whichever convention existing components in the repo currently use for the area you're touching. If starting fresh, ship flat named exports only — add a composed `Object.assign` object solely to preserve an existing dot-notation API, never on a new component, where it buys nothing and adds an RSC trap to the public surface permanently:

```ts
// Flat exports (RSC-safe) — the default for anything new
export {Root as DialogRoot, Content as DialogContent, Header as DialogHeader, Title as DialogTitle}

// Composed export — only to preserve an existing dot-notation API, and it has to keep
// the name consumers already type (`Dialog`), or it preserves nothing.
export const Dialog = Object.assign(Root, {Content, Header, Title})
```

Base and presentational parts for the same component intentionally share `<Component><Part>` names across their different entry points — don't prefix or rename base parts to avoid the clash. A file importing both aliases one at the import site. Note this applies to exported **types** as well as components: `AccordionItemProps` will mean structurally different things depending on the entry point, and TypeScript error messages won't disambiguate them, so alias deliberately.

## Accessibility semantics

Keep markup and accessibility semantics flexible. Preserve native semantics, including heading structure, and expose presentational pieces when consumers need control over content, appearance, or semantics — via plain children composition, per the composition rules above. Match the accessibility pattern to the component contract — for established ARIA Authoring Practices Guide patterns (e.g. accordions), prefer the APG semantics and structure over ad hoc native-element defaults. See `modular-ds-accessibility-contract` for the full responsibility matrix across API types.

## Promoting to a config component

As a pattern (e.g. a filtering behavior layered on top of presentational parts) becomes common and well-understood, consider moving it up the spectrum into a config component. Until then, the presentational API is the supported path — don't force premature abstraction.

More agent context in primer/react

15 other files this repository gives its agents.