Astro components are the basic building blocks of any Astro project. They are HTML-only templating components with no client-side runtime. You can spot an Astro component by its file extension:
Astro components are extremely flexible. Often, an Astro component will contain some reusable UI on the page, like a header or a profile card. At other times, an Astro component may contain a smaller snippet of HTML, like a collection of common
<meta> tags that make SEO easy to work with. Astro components can even contain an entire page layout.
When your Astro component does need client-side interactivity, you can add standard HTML
<script> tags or UI Framework components.
Component StructureSection titled Component Structure
An Astro component is made up of two main parts: the Component Script and the Component Template. Each part performs a different job, but together they provide a framework that is both easy to use and expressive enough to handle whatever you might want to build.
The Component ScriptSection titled The Component Script
Astro uses a code fence (
---) to identify the component script in your Astro component. If you’ve ever written Markdown before, you may already be familiar with a similar concept called frontmatter. Astro’s idea of a component script was directly inspired by this concept.
- importing other Astro components
- importing other framework components, like React
- importing data, like a JSON file
- fetching content from an API or database
- creating variables that you will reference in your template
The Component TemplateSection titled The Component Template
The component template is below the code fence and determines the HTML output of your component.
If you write plain HTML here, your component will render that HTML in any Astro page it is imported and used.
<script> tags, imported components, and special Astro directives. Data and values defined in the component script can be used in the component template to produce dynamically-created HTML.
Component-based designSection titled Component-based design
Components are designed to be reusable and composable. You can use components inside of other components to build more and more advanced UI. For example, a
Button component could be used to create a
Component PropsSection titled Component Props
An Astro component can define and accept props. These props then become available to the component template for rendering HTML. Props are available on the
Astro.props global in your frontmatter script.
Here is an example of a component that receives a
greeting prop and a
name prop. Notice that the props to be received are destructured from the global
This component, when imported and rendered in other Astro components, layouts or pages, can be passed these props as attributes:
You can also define your props with TypeScript with a
Props type interface. Astro will automatically pick up the
Props interface in your frontmatter and give type warnings/errors. These props can also be given default values when destructured from
Component props can be given default values to use when none are provided.
SlotsSection titled Slots
<slot /> element is a placeholder for external HTML content, allowing you to inject (or “slot”) child elements from other files into your component template.
By default, all child elements passed to a component will be rendered in its
This pattern is the basis of an Astro layout component: an entire page of HTML content can be “wrapped” with
<SomeLayoutComponent></SomeLayoutComponent> tags and sent to the component to render inside of common page elements defined there.
Named SlotsSection titled Named Slots
An Astro component can also have named slots. This allows you to pass only HTML elements with the corresponding slot name into a slot’s location.
Slots are named using the
To inject HTML content into a particular slot, use the
slot attribute on any child element to specify the name of the slot. All other child elements of the component will be injected into the default (unnamed)
slot="my-slot" attribute on the child element that you want to pass through to a matching
<slot name="my-slot" /> placeholder in your component.
Fallback Content for SlotsSection titled Fallback Content for Slots
Slots can also render fallback content. When there are no matching children passed to a slot, a
<slot /> element will render its own placeholder children.
HTML ComponentsSection titled HTML Components
Astro supports importing and using
.html files as components or placing these files within the
src/pages/ subdirectory as pages. You may want to use HTML components if you’re reusing code from an existing site built without a framework, or if you want to ensure that your component has no dynamic features.
HTML components must contain only valid HTML, and therefore lack key Astro component features:
- They don’t support frontmatter, server-side imports, or dynamic expressions.
<script>tags are left unbundled, treated as if they had
- They can only reference assets that are in the
Next StepsSection titled Next Steps
📚 Learn about using UI framework components in your Astro project.