Support overriding Badge and Aside

[evadecker]

What version of starlight are you using?

v0.25.0

What is your idea?

It would be nice to be able to override Badge and Aside the same way that other components can be overridden.

Why is this feature necessary?

Currently there's no easy way to swap out Starlight's Badge and Aside for a different implementation. It would be nice to be able to customize these components and override them the same way that you can for other parts of Starlight. For example, I don't believe it's currently possible to swap out the icons in Aside for something else, or to add a custom icon to Badge.

Do you have examples of this feature in other projects?

No response

Participation

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

[villeodell]

It would be valuable if all of Astro's built in UI components could be extended / overridden:

• Cards
• Link Cards
• Card Grids
• Asides
• Badges
• Code
• File Tree
• Icons
• Link Buttons
• Steps
• Tabs

Why is this feature necessary?

Documentation is often a key touchpoint for communicating to users, requiring consistent design language and functionality across all elements. While Starlight provides an excellent set of UI components, users cannot customize them through the standard component override system.

By making all the built in UI components customizable, we can more easily do things like:

• Maintain design consistency across all documentation
• Add specialized functionality for specific use cases
• Improve accessibility for a target audience
• Integrate analytics or tracking where needed
• Add interactive features for better user engagement

[HiDeoo]

Thanks for your feedback.

users cannot customize them through the standard component override system

While technically true, component overrides is meant to provide a mechanism to customize the appearance of components that are directly rendered by Starlight.

All the other components listed in your message are user components, which are not directly rendered by Starlight but by users themselves. As such, users can import and use any other component library they want to get the desired consistency of appearance, e.g.:

import { Card } from 'custom-design-system/components';

<Card title="Check this out">Interesting content you want to highlight.</Card>

[villeodell]

Ah! I wasn't making the distinction between the components directly rendered by Starlight and the "user" components I listed and was trying to override them the same way. It seems obvious in hindsight, but it didn't click until I read your reply.

I'm new to both Astro and Starlight so it might be just me who got tripped up by this, but I think I didn't make the distinction at first because I just followed the guidance in Overriding Components without giving it too much thought. When it didn't work for things like Aside, I went back to the docs, followed the link to the Overrides Reference where it talks about Starlights "built in components" and thought, oh the things like Cards, Asides, etc.. (to me they were also "built-in" Starlight components) aren't supported for overriding yet for some reason.

It might be helpful for others like me to have a small note in the docs somewhere that distinguishes more clearly between the two sets of components that both come with Starlight, the special ones that Starlight itself renders and need to be overridden in the starlight config, and the ones that are just normal Astro components and should be treated as such (assuming I have it right now).

Thanks very much for your reply!