Starlight React Islands Best Practices

When a React island is rendered inside Starlight page content, remember that it lives inside .sl-markdown-content. That means Starlight’s markdown spacing rules can affect your component even when the React code itself looks correct.

Rule of Thumb

Wrap interactive UI blocks in a container with the not-content class.

Use this for:

• filter bars
• search controls
• tab-like custom toolbars
• form controls rendered as React islands

Why This Matters

Starlight adds vertical spacing between generic markdown content blocks. If your island renders wrapper elements like <div> siblings, Starlight may apply margin-top to items after the first one.

This can create bugs like:

• the first dropdown looking higher than the others
• controls in the same row appearing vertically misaligned
• React UI looking correct in isolation but broken inside Starlight pages

Recommended Pattern

return (
  <div className="not-content">
    <div className="flex flex-wrap items-center gap-2">
      <MyControl />
      <MyControl />
      <MyControl />
    </div>
  </div>
);

Activities Filter Bug

The Activities filter row hit exactly this issue. The dropdowns were rendered in a shared flex row, but Starlight treated the wrappers as markdown content and added spacing to later siblings.

The fix was to:

• add not-content to the filter container
• keep the controls inside that protected wrapper
• avoid relying on visual tweaks alone when only the first item appears wrong

Debugging Tip

If only the first element in a repeated UI row looks different, suspect inherited content styling before changing the component internals. In Starlight, inspect .sl-markdown-content and any selectors that exclude :where(.not-content *).