Skip to content


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:

title: Welcome to my docs
import SomeComponent from '../../components/SomeComponent.astro';
import AnotherComponent from '../../components/AnotherComponent.astro';
<SomeComponent prop="something" />
Components can also contain **nested content**.

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.

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

Built-in components

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


You can display a tabbed interface using the <Tabs> and <TabItem> components. Each <TabItem> must have a label to display to users. Use the optional icon attribute to include one of Starlight’s built-in icons next to the label.

import { Tabs, TabItem } from '@astrojs/starlight/components';
<TabItem label="Stars" icon="star">
Sirius, Vega, Betelgeuse
<TabItem label="Moons" icon="moon">
Io, Europa, Ganymede

The code above generates the following tabs on the page:

Sirius, Vega, Betelgeuse


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.

import { Card, CardGrid } from '@astrojs/starlight/components';
<Card title="Check this out">Interesting content you want to highlight.</Card>
<Card title="Stars" icon="star">
Sirius, Vega, Betelgeuse
<Card title="Moons" icon="moon">
Io, Europa, Ganymede

The code above generates the following on the page:

Check this out

Interesting content you want to highlight.


Sirius, Vega, Betelgeuse


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.

import { LinkCard, CardGrid } from '@astrojs/starlight/components';
title="Customizing Starlight"
description="Learn how to make your Starlight site your own with custom styles, fonts, and more."
<LinkCard title="Authoring Markdown" href="/guides/authoring-content/" />
<LinkCard title="Components" href="/guides/components/" />

The above code generates the following on the page:


Asides (also known as “admonitions” or “callouts”) are useful for displaying secondary information alongside a page’s main content.

An <Aside> can have an optional type of note (the default), tip, caution or danger. Setting a title attribute overrides the default aside title.

import { Aside } from '@astrojs/starlight/components';
<Aside>A default aside without a custom title.</Aside>
<Aside type="caution" title="Watch out!">
A warning aside *with* a custom title.
<Aside type="tip">
Other content is also supported in asides.
// A code snippet, for example.
<Aside type="danger">Do not give your password to anyone.</Aside>

The above code generates the following on the page:

Starlight also provides a custom syntax for rendering asides in Markdown and MDX as an alternative to the <Aside> component. See the “Authoring Content in Markdown” guide for details of the custom syntax.


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.

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:

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.

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:

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

File Tree

Use the <FileTree> component to display the structure of a directory with file icons and collapsible sub-directories.

Specify the structure of your files and directories with an unordered Markdown list inside <FileTree>. Create a sub-directory using a nested list or add a / to the end of a list item to render it as a directory without specific content.

The following syntax can be used to customize the appearance of the file tree:

  • Highlight a file or directory by making its name bold, e.g. ****.
  • Add a comment to a file or directory by adding more text after the name.
  • Add placeholder files and directories by using either ... or as the name.
import { FileTree } from '@astrojs/starlight/components';
- astro.config.mjs an **important** file
- package.json
- src
- components
- **Header.astro**
- pages/

The above code generates the following on the page:

  • astro.config.mjs an important file
  • package.json
  • Directorysrc
    • Directorycomponents
      • Header.astro
  • Directorypages/


Use the <Steps> component to style numbered lists of tasks. This is useful for more complex step-by-step guides where each step needs to be clearly highlighted.

Wrap <Steps> around a standard Markdown ordered list. All the usual Markdown syntax is applicable inside <Steps>.

import { Steps } from '@astrojs/starlight/components';
1. Import the component into your MDX file:
import { Steps } from '@astrojs/starlight/components';
2. Wrap `<Steps>` around your ordered list items.

The code above generates the following on the page:

  1. Import the component into your MDX file:

    import { Steps } from '@astrojs/starlight/components';
  2. Wrap <Steps> around your ordered list items.


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.

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.