[RFC] Decide whether to add a sidebar.renderIcon API endpoint

[Sidnioulz]

Summary

The sidebar allows users to customise React nodes for the text portion of a sidebar item via renderLabel. With a11y compliance, we also need to add renderAriaLabel for a screen-reader counterpart.

There are weak signals in favour of allowing the customisation of renderIcon. This RFC asks the question of whether we should decide to add this additional API endpoint.

Problem Statement

Sidebar item text can be customised, but not the icons. Icons always depend on the item [sub]type (group, component, docs, story, test).

In Storybook 10, users can create their own content types (for which they may want custom icons). They need to use a pseudo element positioned over the actual icon to handle this use case. Reported use cases are:

• custom indexers, that possibly use Vite plugins to do something different than display a docs or story (e.g. https://stackblitz.com/~/github.com/Sidnioulz/storybook-sidebar-urls that adds external URLs to the sidebar)
• The tab addon type, that lets users add custom content to a specific sidebar entry; as we remove this in SB11, the alternative for this would be custom indexers
• Customize the sidebar icons #30728 is a feature request where the underlying use case was not reported

Besides, themability would be simplified if we added renderIcon. At the moment and until theming 2.0 is implemented, it is difficult to change the colours of icons. It's difficult to target a specific type of icon (#18336).

Non-goals

No response

Implementation

Option 1 - do not add API endpoint:

• Review how we style icons to make it easier to customise icon colours, or delay that issue till theming 2.0
• Continue to document the pseudo-element trick in the custom indexers doc page
• Document the pseudo-element trick as a workaround in relevant issues

Option 2 - add endpoint:

• Add a sidebar.renderIcon endpoint
• If defined by users, call it to receive a ReactNode to show instead of the icon
• Add tests
• Add docs

Prior Art

sidebar.renderLabel, which is primarily useful for badges/status addons

Deliverables

No response

Risks

There is very little direct user demand for this. The needs where it would come handy are fairly niche, with little demand as well. Even though the maintenance surface is reasonable (we already have renderLabel working identically), the ROI is difficult to justify.

Unresolved Questions

• Using a to do list makes it easy to resolve the questions as we move the RFC along.

Alternatives considered / Abandoned Ideas

No response

[MichaelArestad]

I'd like to hear from individual users on their use cases before we do anything like this. I can see the following options as a possibility:

1. Ability to customize the icon*
2. Ability to hide the icon

If we did allow icon customization, we would need to allow the user to use their own icon. We should not take icon requests for our icon library or it will be difficult to maintain.

The methods described above can work. A good start might be to use class names that are human readable to make the pseudo element trick easier and more obvious.

[Sidnioulz]

Class names would solve the colour issue, not the pseudo element trick though. That trick could be documented in a code snippet or example for adventurous folks, or we could document it as a workaround on open issues and leave it at that.

[shilman]

If a theming overhaul would fix this, I would prefer to do it that way rather than increase our API surface area.