It's currently impossible to override some components, make it be possible...

[babakfp]

What version of starlight are you using?

0.41.7

What is your idea?

The docs say that I can customize TableOfContents.astro.

Is that true? Kind of true and also not true.

That file contains a code importing the TableOfContentsList.astro component; This file is not exposed publicly using the exports property from package.json. @astrojs/starlight does not provide a way to import TableOfContentsList.astro.

What should happen then?

1. I copy built-in component code as is.
2. Do as little at possible changes to make it work.
3. I change this source code:

import TableOfContentsList from '../components-internals/TableOfContents/TableOfContentsList.astro';

into this:

import TableOfContentsList from '@astrojs/starlight/components-internals/TableOfContents/TableOfContentsList.astro';

and that's it, it should just work now!

It's not only the components-internals that is needed to be exported, it's other folders and files too. The whole starlight package (packages/starlight) (all paths from root and nexted) should be exported as is (excluding things like vitest.config.ts).

As far as I checked, these are required:

    "./components-internals/*": "./components-internals/*",
    "./user-components/*": "./user-components/*",
    "./integrations/*": "./integrations/*",
    "./utils/*": "./utils/*",
    "./style/*": "./style/*",
    "./constants": "./constants.ts"

Why is this feature necessary?

Because without it, it's not possible no just simply override an Astro component. Maybe I like 99% of what a built-in component does, but i would like to change only 1% of it, currently it's no possible.

Do you have examples of this feature in other projects?

No response

Participation

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

Related

• Add TableOfContentsList to Module Exports / Allow Overrides #2071

[delucis]

Thanks for the discussion. Could you describe your specific use case? What changes are you trying to make to the table of contents?

[babakfp]

For TableOfContents.astro specifically I wanted to replace toc && ( with toc && toc.items.lenght > 1 && (, to hide toc menu when there was no items.

Workaround

<script is:inline>
    document.documentElement.dataset.theme = "dark"

    window.addEventListener('DOMContentLoaded', () => {
        if (document.querySelectorAll('starlight-toc > nav > ul > li').length < 2) {
            document.querySelector('.right-sidebar-panel').remove()
        } else {
            document.querySelector('.right-sidebar-panel').setAttribute('style', 'opacity: 1')
        }
    })
</script>

There was more that I wanted to do, like with other components, but I forgot to be honest 🤣.

I changed the project a lot so... I kind of don't need any of this anymore. Kept markdown + search only...

Still, it would be great to just copy paste things into your project (just like how shadcn is) and change things how you like, and done!

Some things can be done with CSS, but it's cleaner to just override it. There would be no need for hacky CSS that you need to overrite styles carefully on different sizes and make sure you did't break things and find out about it later...

Off topic but related

Remove import friction

Let's say I copy paste this code:

import config from 'virtual:starlight/user-config';
import LanguageSelect from 'virtual:starlight/components/LanguageSelect';
import { localizedUrl } from '../utils/localizedUrl';
import Select from './Select.astro';
import ContentNotice from './ContentNotice.astro';
import '../style/markdown.css';

I would need to adjust so many things, get rid of red errors lines, to just make it work, then to begin doing my changes.

It would be great if there was zero friction. Meaning the source code of starlight to be this:

import config from '@astrojs/starlight/user-config';
import LanguageSelect from '@astrojs/starlight/components/LanguageSelect';
import { localizedUrl } from '@astrojs/starlight/utils/localizedUrl';
import Select from '@astrojs/starlight/components/Select.astro';
import ContentNotice from '@astrojs/starlight/components/ContentNotice.astro';
import '@astrojs/starlight/style/markdown.css';

The built-in components could just work when users copies them over to their project (to override). It would make it straght forward and reduce the inconvenience of overriding components.

I'm not sure if technically some of things imports like virtual:starlight and user-config would work or not, but if did it would be awesome!

Separation of concerns

In a astro component, take HTML, CSS, JS and put them into their own individual files.

so then when overriding, there would be less things to worry about. for example when wanting to only edit the html parts, you wouldn't need to copy in all the JS and CSS too.

I'm not too sure about this one.

[delucis]

Thanks! Re: your specific use case, maybe you’re looking for the “Reuse a built-in component” section of the docs, so you can do:

---
import Default from '@astrojs/starlight/components/TableOfContents.astro';

const { toc } = Astro.locals.starlightRoute
---

{toc.items.length > 1 && <Default><slot /></Default>}

In general the API is not designed for copying the original implementation, although I know sometimes it is helpful to do so. Part of the issue is we consider those imports as component “internals” and can’t guarantee they won’t break your override if we change them, so it’s kind of intentional that they are not all available as imports.

We have been trying to keep as much logic as possible out of components though to make this less of an issue: the more stuff is in the starlightRoute object, the easier it is to copy or reimplement things.