Skip to content
Starlight

Components

Components let you easily reuse a piece of UI or styling consistently. Examples might include a link card or a YouTube embed. Starlight supports the use of components in MDX files and provides some common components for you to use.

Learn more about building components in the Astro Docs.

Using a component

You can use a component by importing it into your MDX file and then rendering it as a JSX tag. These look like HTML tags but start with an uppercase letter matching the name in your import statement:

src/content/docs/example.mdx
---
title: Welcome to my docs
---


import SomeComponent from '../../components/SomeComponent.astro';
import AnotherComponent from '../../components/AnotherComponent.astro';


<SomeComponent prop="something" />


<AnotherComponent>
  Components can also contain **nested content**.
</AnotherComponent>

Because Starlight is powered by Astro, you can add support for components built with any supported UI framework (React, Preact, Svelte, Vue, Solid, Lit, and Alpine) in your MDX files. Learn more about using components in MDX in the Astro docs.

Compatibility with Starlight’s styles

Starlight applies default styling to your Markdown content, for example adding margin between elements. If these styles conflict with your component’s appearance, set the not-content class on your component to disable them.

src/components/Example.astro
<div class="not-content">
  <p>Not impacted by Starlight’s default content styling.</p>
</div>

Built-in components

Starlight provides some built-in components for common documentation use cases. These components are available from the @astrojs/starlight/components package.

Tabs

You can display a tabbed interface using the <Tabs> and <TabItem> components. Each <TabItem> must have a label to display to users.

src/content/docs/example.mdx
import { Tabs, TabItem } from '@astrojs/starlight/components';


<Tabs>
  <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem>
  <TabItem label="Moons">Io, Europa, Ganymede</TabItem>
</Tabs>

The code above generates the following tabs on the page:

Sirius, Vega, Betelgeuse

Cards

You can display content in a box matching Starlight’s styles using the <Card> component. Wrap multiple cards in the <CardGrid> component to display cards side-by-side when there’s enough space.

A <Card> requires a title and can optionally include an icon attribute set to the name of one of Starlight’s built-in icons.

src/content/docs/example.mdx
import { Card, CardGrid } from '@astrojs/starlight/components';


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


<CardGrid>
  <Card title="Stars" icon="star">
    Sirius, Vega, Betelgeuse
  </Card>
  <Card title="Moons" icon="moon">
    Io, Europa, Ganymede
  </Card>
</CardGrid>

The code above generates the following on the page:

Check this out

Interesting content you want to highlight.

Stars

Sirius, Vega, Betelgeuse

Moons

Io, Europa, Ganymede

Use the <LinkCard> component to link prominently to different pages.

A <LinkCard> requires a title and an href attribute. You can optionally include a short description or other link attributes such as target.

Group multiple <LinkCard> components in <CardGrid> to display cards side-by-side when there’s enough space.

src/content/docs/example.mdx
import { LinkCard, CardGrid } from '@astrojs/starlight/components';


<LinkCard
  title="Customizing Starlight"
  description="Learn how to make your Starlight site your own with custom styles, fonts, and more."
  href="/guides/customization/"
/>


<CardGrid>
  <LinkCard title="Authoring Markdown" href="/guides/authoring-content/" />
  <LinkCard title="Components" href="/guides/components/" />
</CardGrid>

The above code generates the following on the page:

Customizing Starlight Learn how to make your Starlight site your own with custom styles, fonts, and more.
Authoring Markdown
Components

Icon

Starlight provides a set of common icons that you can display in your content using the <Icon> component.

Each <Icon> requires a name and can optionally include a label, size, and color attribute.

src/content/docs/example.mdx
import { Icon } from '@astrojs/starlight/components';


<Icon name="star" color="goldenrod" size="2rem" />

The code above generates the following on the page:

All icons

A list of all available icons is shown below with their associated names. Click an icon to copy the component code for it.

Code

Use the <Code> component to render syntax highlighted code when using a Markdown code block is not possible, for example, to render data coming from external sources like files, databases, or APIs.

See the Expressive Code “Code Component” docs for full details of the props <Code> supports.

src/content/docs/example.mdx
import { Code } from '@astrojs/starlight/components';


export const exampleCode = `console.log('This could come from a file or CMS!');`;
export const fileName = 'example.js';
export const highlights = ['file', 'CMS'];


<Code code={exampleCode} lang="js" title={fileName} mark={highlights} />

The code above generates the following on the page:

example.js
console.log('This could come from a file or CMS!');

Imported Code

Use Vite’s ?raw import suffix to import any code file as a string. You can then pass this imported string to the <Code> component to include it on your page.

src/content/docs/example.mdx
import { Code } from '@astrojs/starlight/components';
import importedCode from '/src/env.d.ts?raw';


<Code code={importedCode} lang="ts" title="src/env.d.ts" />

The code above generates the following on the page:

src/env.d.ts
/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />