Custom components

In addition to all available Starlight components, Astro Docs uses several custom components that are available for use in any .mdx files. Note that these components cannot be used for docs that live in the astro core repo (e.g. configuration reference, error reference docs). Be sure to always check a preview of your components in the browser to ensure they are rendering properly.

Custom components

These components must be imported at the top of the page from '~/components/' unless specified otherwise. They are built locally inside of Astro and are not available as standard Starlight components.

Badge Component

Sometimes it is helpful to add a small badge to some content to label or highlight it. You can use the <Badge /> component for this.

Badges work best when they only contain a single word or — at a push — two words. Think of them as a tag or label for something, not a way to highlight longer passages of text.

import Badge from '~/components/Badge.astro';

<Badge>Nice</Badge>

By default, the badge uses a muted colour scheme to blend in. It also has an accented variant that can be used if you need it to stand out more from the surrounding context:

<Badge variant="accent">Wow!</Badge>

Examples

The Editor Setup page uses <Badge /> to distinguish community and official editor support.
The Deployment guides navigation component uses <Badge /> internally to label the deployment types each service supports.

Since Component

As features are added to Astro, we document when they were added. This allows users to easily see if the version of Astro (or other packages) they are running supports a specific feature as described in the docs.

Use the <Since /> component to display this information in a standardized way.

This component takes two props:

A v prop, which indicates the version of the package in which the feature was added.
A pkg prop, which indicates which package is being documented. This is optional and will default to 'astro'. It is only required when using <Since /> for other packages.

import Since from '~/components/Since.astro';

<p><Since v="1.0.0" /></p>

This will render the text “Added in: astro@1.0.0”.

The advantages of using the component include:

“Added in” is automatically translated on pages in other languages.
The passed version is checked against the current package version and “NEW” or “BETA” badges will be added automatically based on data from npm.

Examples

The standard usage of this component is on its own line, immediately following the feature’s heading, for example:

## `Astro.clientAddress`

<p><Since v="1.0.0-rc" /></p>

Specifies the IP address of the request. This property is only available when building for SSR (server-side rendering) and should not be used for static sites.

Or, it can be used in a short block of information, for example:

### `server.host`

Type: `string | boolean`
Default: `false`
<Since v="0.24.0" />

Set a custom package name for integrations and other packages. These will begin with @astrojs/:

<Since v="2.1.0" pkg="@astrojs/rss" />

Latest version Component

Use the <Version /> component to automatically fetch and display the latest version of Astro or one of its packages. This component must receive a valid package name from the npm registry as its pkgName prop.

Astro's latest version:  <Version pkgName="astro" />

This will render Astro’s latest version: v1.2.1.

You can see the <Version /> component used at the top of the page in our integration guides. This component is only updated when the docs site is rebuilt, so there may be a slight delay if a new version of the docs site has not been published since a package release.

Custom Tabs Components

Astro Docs uses two custom variants that pre-date Starlight’s <Tabs> component: <PackageManagerTabs> and <UIFrameworkTabs>. Other custom components may be added over time. You can find all existing Tabs variations in src/components/tabs/.

Note that these components share state, so if a reader changes the active tab of one <PackageManagerTabs> or <UIFrameworkTabs> component, then all other instances of this component on the same page will also change. This allows the reader to see the same content choice by default while reading through the entire page.

These custom components were built for Astro Docs before this feature was available in Starlight. They are still in use throughout the docs, but may be updated in the future. We suggest using Starlight’s <Tabs> directly for all other situations.

Examples

Import the component at the top of the .mdx file:

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

Then, create a <Fragment> for each tab. The fragment’s slot name will identify the tab label and the content between the opening and closing <Fragment>...</Fragment> tags will be the panel content.

Here is an example of <PackageManagerTabs> showing the create astro commands from our Automatic Astro Installation page.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # create a new project with npm
  npm create astro@latest
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # create a new project with pnpm
  pnpm create astro@latest
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # create a new project with yarn
  yarn create astro
  ```
  </Fragment>
</PackageManagerTabs>

Astro Docs uses a <RecipeLink> component for displaying links to recipes with consistent styling. This is helpful when some page content has one or more relevant recipes you want to link to.

<RecipeLink> takes a single slugs prop, which is an array of the slugs of the recipes you want to link to. A slug has no leading or trailing slash and should match the language of the page you are currently on. For example, use pt-br/recipes/captcha on a Brazilian Portuguese page and not en/recipes/captcha.

import RecipeLinks from "~/components/RecipeLinks.astro";

<RecipeLinks slugs={["en/recipes/captcha", "en/recipes/build-forms-api"]}/>

Starlight components

Please see Starlight’s component documentation for all available Starlight components. The ones most often used in Astro docs include:

Aside Component

Use only for information that is complementary but not necessary. This can also be used to call out something important that has not already been said.

Astro Docs uses the following variants:

note: to provide complementary or tangential information that does not belong in the regular paragraph text
tip: to suggest an action that may help, but is not essential
caution: to warn of dangerous conditions such as security issues, or data loss

This syntax is automatically recognized by Starlight and no import is required:

:::tip
It’s best to avoid using `<blockquote>` for things that aren’t quotes.
:::

The syntax also supports custom titles for the asides:

:::caution[Deprecated]
Using `<blockquote>` for notes is deprecated.
:::

Use asides sparingly. Asides create visual clutter and distract the reader. If everything is important, then nothing is important! Most contributions that include asides are rewritten or rejected.

Use the following guidelines to decide when (not to!) use an aside:

Do not use a note to “add a new piece of information” to docs. Essential information belongs in paragraph text.
Do not prompt the reader to “remember” (to do) earlier content or steps. There is no need to duplicate information.
Do not use a “tip” when an action is necessary. That is not a tip; that is a requirement.
Do not use a “caution” unless there is a risk of danger.

You can see all three currently-used styles (we don’t have any “danger” yet!) in action on the Astro Components Page.

FileTree Component

Import and use the Starlight <FileTree /> component to produce collapsable file trees in docs. Use hyphens (-) at different tab depths to show the file structure.

Please add a / at the end of a folder name, and file extensions after file names.

import { FileTree } from '@astrojs/starlight/components';

### Example Project Tree

A common Astro project directory might look like this:

<FileTree>
- public/
  - robots.txt
  - favicon.svg
  - social-image.png
- src/
  - components/
    - Header.astro
    - Button.jsx
  - layouts/
    - PostLayout.astro
  - pages/
    - posts/
      - post1.md
      - post2.md
      - post3.md
    - index.astro
  - styles/
    - global.css
- astro.config.mjs
- package.json
- tsconfig.json
</FileTree>

Hightlighting is available by writing an item in bold. Inline comments may also be added.

<FileTree>
- folder/
  - file.js
  - **highlighted-file.ts**
  - file.astro With an inline comment too
</FileTree>

Directoryfolder/
- file.js
- highlighted-file.ts
- file.astro With an inline comment too

Steps Component

Import and use the Starlight <Steps> component to style numbered lists of tasks.

Remember, not every ordered list is a list of steps to follow! Only use this to show a linear sequence of instructions, and be sure to indent paragraphs and code blocks within each list item.

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

import { Steps } from '@astrojs/starlight/components';

<Steps>

1. Import the component into your MDX file:

   ```js
   import { Steps } from '@astrojs/starlight/components';
   ```

2. Wrap `<Steps>` around your ordered list items.

</Steps>

The code above generates the following on the page:

Import the component into your MDX file:

import { Steps } from '@astrojs/starlight/components';

Wrap <Steps> around your ordered list items.

Custom components