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:

Stars

Sirius, Vega, Betelgeuse

Moons

Io, Europa, Ganymede

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

Tip

Use a card grid on your home page to display your project’s key features. Add the stagger attribute to shift the second column of cards vertically and add visual interest:

<CardGrid stagger>
  <!-- cards -->
</CardGrid>

Link Cards

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.

up-caret down-caret right-caret right-arrow left-arrow bars translate pencil pen document add-document setting external moon sun laptop open-book information magnifier forward-slash close error warning approve-check-circle approve-check rocket star puzzle list-format random github gitlab bitbucket codePen discord gitter twitter x.com mastodon codeberg youtube threads linkedin twitch microsoftTeams instagram stackOverflow telegram rss facebook email reddit patreon slack matrix openCollective

Code

Starlight uses Expressive Code to render Markdown and MDX code blocks. 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!');

Code transclusion

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" />