Support external icons since built-in icons are too limited

[dhruvkb]

What version of starlight are you using?

0.5.1

What is your idea?

Since the built-in icons in Starlight are too limited, it would be great if the Card component could work with a different icon set like Font Awesome, Heroicons or Bootstrap.

Why is this feature necessary?

Starlight's built in icon set is extremely limited (~38). The option to integrate with a different icon set would expand the available number of glyphs considerably.

Do you have examples of this feature in other projects?

No response

Participation

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

[delucis]

Thanks for the issue! We’ve adding a few manually so far, but may be worth expanding or supporting customisation. The non-logo icons Starlight currently uses are from the Unicons set: https://github.com/Iconscout/unicons

[lorenzolewis]

Could we look at integrating with https://github.com/natemoo-re/astro-icon/tree/next somehow for this? @natemoo-re is using Iconify to back it and that has the Unicons set in it.

I'm not sure how an "integration within an integration" to have starlight handle this all internally or if this would have to be another layer.

An additional option could be pointing people to that package once component replacement is a think.

[delucis]

I could chat with @natemoo-re‚ it’s definitely an idea! Not sure when natemoo-re/astro-icon#111 might be released.

[lschierer]

with iconify's webcomponent support, this would just be adding the import statement import 'iconify-icon'; to the base layout page, you can then use

<iconify-icon icon="mdi:caret-down-outline"></iconify-icon>

or any other icon where ever you like in the mdx pages.

[aleclarson]

Some guidance on customizing the built-in icons (adding new ones or overriding existing ones) would be very much appreciated!

[aleclarson]

For now, we are patching @astrojs/starlight with pnpm 😅

[delucis]

Ah yeah, we don’t really have any guidance at the moment — the system is basically hardcoded. Looking into maybe using https://github.com/natemoo-re/astro-icon to support this.

[HiDeoo]

Sharing a small note I wrote some time ago on how to use Iconify icons in Starlight by using unplugin-icons.

[omundy]

Great tutorial! However having trouble importing icons from the list. For example, bookmark exists, but not bookmark-full
https://icon-sets.iconify.design/?query=bookmark&search-prefix=uil

[HiDeoo]

The bookmark-full icon you shared is from the uil namespace so the complete import would be:

import UilBookmarkFull from '~icons/uil/bookmark-full';

You can find a working example on this StackBlitz page.

Such import can also be found on the icon search link you shared by following these steps:

[andrii-bodnar]

It would also be great to have a way to customize the icon for the Card component.

For example, by passing an Icon component itself, as in the Nextra's Card component.

[Sidnioulz]

Hey folks,

I think there should be a feature to add icons to the built-in set regardless of options to add external icons to our own pages. Starlight tabs, for instance, are only able to load icons through this mechanism.

It shouldn't be too hard to take monolayer SVGs and pass them through a loader pipeline that transforms them to the format currently used by built-in icons. Is this a contribution the maintainers would be keen to receive?

Or would the maintainers prefer to receive a contribution to automatically inject src/icons/* content into the built-in set through astro-icon?

Or is there a rationale why the built-in set should remain unchanged?

Thanks,

[ghostdevv]

I'm finding the limited number of icons to be a pain point with Starlight at the moment. If it would be accepted I'm happy to make a PR to add this feature request. Either with astro-icon or unplugin-icons. Both options are backed by iconify.

I think unplugin-icons would be better since, in the case that someone wants to use an icon outside of an Astro component, it would already be configured to work (also one less dependency as you wouldn't need to add unplugin-icons). However, I'm not currently confident we could keep the Icon component (and subsequent internal use of it) with this approach, which I think is important. So it's likely we would need to use astro-icon. I'm not too worried about this since they're both backed by iconify, and I imagine that most people using starlight are using mostly writing Astro anyway.

Regardless of which direction, I think it would be ideal to promote consistency. This would mean we keep using allowing use of icons from unicons without a prefix, with any other sets requiring one (e.g. the already supported seti icons). Unicons has 1206 icons at the time of writing, which solves problem of Starlight lacking icons, while maintaining consistency, and giving users the choice of a different icon set if they want it.

Given this I'm hoping we could do this without a breaking change. However, that would depend on whether the icons we currently have are using different names than found in unicons. We may be able to mitigate this by temporarily adding a warning and remapping any icon names that need changing in user code. This also assumes that all the icons we currently use are from actually from unicons, I don't know.

Since I haven't tried to implement this yet, it's largely speculation. However, I did spend a while researching this and reading the docs/source code of unplugin-icons and astro-icon. Based on that I'm reasonably confident this can be done with astro-icon, and curious whether it could be with unplugin-icons. I also took some time to go through the comments in this thread, and while there aren't many, it seems like there is some consensus around iconify. I've had a good experience with it in the past too.

Let me know your thoughts!

[HiDeoo]

Thanks for the detailed write-up! Only sharing a few points that comes to my mind at the moment:

• unplugin-icons is already fairly easy to use in Starlight, I have an example available here so if someone really needs more icons, I don't think they would be entirely blocked.
• All Starlight icons will be soon available in asides, and as it's in a context where we cannot use components, we would still need some custom code to handle this case (probably Iconify iconToSVG)
• Would need to see if any of the work could potentially intersect or rely on the future built-in SVG Components
• I'm pretty sure some current icons are from Unicons but with a different name.

[ghostdevv]

unplugin-icons is already fairly easy to use in Starlight, I have an example available here so if someone really needs more icons, I don't think they would be entirely blocked.

I think this feature request is about the icons available in core, that you use with the built-in components. In user land your blog post is awesome, and my initial draft made note of it! It just meant that it would be cool if starlight used unplugin-icons just to reduce configuration required by the user. I don't think of this as a hard requirement though.

[HiDeoo]

Oh definitely, it was mostly a follow-up to the "curious whether it could be with unplugin-icons" interrogation, and from my experience, I don't think there would be any blocker if we end up using this approach instead of astro-icon for some reason.

I think I also have a few other notes regarding this topic in a thread where we were discussing the feature. I'll make sure to share them here if I manage to find them and they're still relevant.

Really exciting feature request 🌟

[ghostdevv]

Oh definitely, it was mostly a follow-up to the "curious whether it could be with unplugin-icons" interrogation, and from my experience, I don't think there would be any blocker if we end up using this approach instead of astro-icon for some reason.

Ah! So it's whether I could recreate the <Icon name="..." /> pattern with unplugin-icons, which I'm confident I could (at least in the same way). unplugin-icons is effectively a vite plugin, where astro-icon appears to be able to work dynamically. This seems to be since with astro-icon you can optionally bundle all the icons from your icon chosen set(s) into the server bundle. I'm not sure if unplugin-icons has that feature. Now, it's debatable whether this matters, it's a documentation site after all, but it's still worth considering. There is also the question of whether unplugin-icons would work with our current components (e.g. <Card icon="..."). I'm sure I could make something that statically allows you to use unplugin-icons with this, but we'd then be loosing our on the dynamic-ness we currently have - which people might want to keep, I don't know.

I think I also have a few other notes regarding this topic in a thread where we were discussing the feature. I'll make sure to share them here if I manage to find them and they're still relevant.

That would be awesome

Really exciting feature request 🌟

🥳

[moonmeister]

Don't have a ton to add here. Most of our issues have been covered I believe so I'll be brief.

1. We have corporate design icon assets that were subtly different from those provided that we wanted to use to override existing icons.
2. We also had new icons for use in components like Cards.

We ended up building a Custom card component that could fallback to internal icons, overriding existing icons in CSS (I would have preferred patch-package but my boss decided against this), and other icons we gave up caring. This feature would save us a lot of headaches and maintenance burden. Thanks all!