Support Islands in mdx files

[nobleach]

What version of starlight are you using?

0.17.4

What is your idea?

I currently am trying to build documentation for a React component library. Some of this library uses JavaScript for click-handlers, references, etc. Attempting to use client:load directives in an .mdx file does not work. Everything is still rendered CSS+HTML only.

Why is this feature necessary?

I'd love to replace Storybook as Starlight provides so much more freedom. I just need to be able to use some client-side JavaScript to test/author components.

Do you have examples of this feature in other projects?

No response

Participation

• I am willing to submit a pull request for this feature.

[delucis]

Hi @nobleach — are you able to share your code? Islands with client: directives in MDX should work already!

[nobleach]

Certainly. Here's an example of a button. In a file called button.mdx with documentation in Markdown:

#### Result

<div className={`balance2024 ${styles.buttonContainer}`}>
  <Button
    client:load
    buttonType="destructive"
    size="md"
    onClick={() => console.log('clicked')}
  >
    Click Me
  </Button>

  <Button
    buttonType="destructive"
    disabled
    size="md"
    onClick={() => console.log('clicked')}
  >
    Disabled
  </Button>
  </div>

That first button should log clicked to the console. I can include much more involved components that use React state if that's helpful, but this encapsulates the problem well. Adding client:load does not seem to render this component client-side.

[delucis]

Thanks. I’m guessing the issue is with the onClick being directly in MDX — I’ve seen something mentioned about that before. It may be that Astro only supports onClick inside JSX/TSX React files, not also in MDX.

[nobleach]

Yeah, that sound plausible. I have other components that use various bits of javascript (to toggle input type from "password" to "text" to reveal a password - for example). One or two that borrow useState from React to store whether things are shown/hidden. Those are affected as well. I did think MDX was supposed to handle those but, it could be faulty recollection.

[delucis]

Yeah, I just investigated a bit and it’s this.

Basically when you create an island in Astro, all props have to be serializable so they can be shipped to the client for hydration, so passing functions etc. won’t work. In some tools, the whole MDX module gets compiled to a React component and shipped, in which case supporting this is possible, but in Astro (and therefore Starlight), the MDX is rendered at build time to static HTML and only the code inside an island component is shipped (if it has a client:* directive). Props are still supported, but these need to be things like strings, numbers, booleans, or objects/arrays of those.

In other words, the following works:

<Button variant="primary" />

But this does not:

<Button onClick={() => console.log("clicked")} />

To work around this, you can wrap your component so that the onClick is set in a JSX/TSX file. Although admittedly if you have a LOT of these, then doing that would be quite annoying.

[nobleach]

Thanks for looking. I'm going to test some components that do things like store state via useState. If those still work, I'd be willing to do some wrapping for the cases where onClick events are passed. Starlight really is a beautiful tool and I've been so happy with the results thus far.

Thanks again.

[nobleach]

I was able to confirm the "wrapping" technique described above worked for my needs. We can close this discussion.