Components

Astro components are the basic building blocks of any Astro project. They are HTML-only templating components with no client-side runtime.

If you know HTML, you already know enough to write your first Astro component.

Astro component syntax is a superset of HTML. The syntax was designed to feel familiar to anyone with experience writing HTML or JSX, and adds support for including components and JavaScript expressions. You can spot an Astro component by its file extension: .astro.

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.

The most important thing to know about Astro components is that they render to HTML during your build. Even if you run JavaScript code inside of your components, it will all run ahead of time, stripped from the final page that you send to your users. The result is a faster site, with zero JavaScript footprint added by default.

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 aim to provide a framework that is both easy to use and expressive enough to handle whatever you might want to build.

---
// Component Script (JavaScript)
---
<!-- Component Template (HTML + JS Expressions) -->

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 ButtonGroup component like so:

---
import Button from './Button.astro';
---
<div>
  <Button title="Button 1" />
  <Button title="Button 2" />
  <Button title="Button 3" />
</div>

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.

You can use the component script to write any JavaScript code that you need to render your template. This can include:

• 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

---
import SomeAstroComponent from '../components/SomeAstroComponent.astro';
import SomeReactComponent from '../components/SomeReactComponent.jsx';
import someData from '../data/pokemon.json';

// Access passed-in component props, like `<X title="Hello, World" />`
const {title} = Astro.props;
// Fetch external data, even from a private API or database
const data = await fetch('SOME_SECRET_API_URL/users').then(r => r.json());
---
<!-- Your template here! -->

The code fence is designed to guarantee that the JavaScript that you write in it is “fenced in.” It won’t escape into your frontend application, or fall into your users hands. You can safely write code here that is expensive or sensitive (like a call to your private database) without worrying about it ever ending up in your user’s browser.

Below the component script, sits the component template. The component template decides 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.

However, Astro’s component template syntax also supports JavaScript expressions, imported components and special Astro directives. Data and values defined (at page build time) in the component script can be used in the component template to produce dynamically-created HTML.

---
// Your component script here!
import ReactPokemonComponent from '../components/ReactPokemonComponent.jsx';
const myFavoritePokemon = [/* ... */];
---
<!-- HTML comments supported! -->

<h1>Hello, world!</h1>

<!-- Use props and other variables from the component script: -->
<p>My favorite pokemon is: {Astro.props.title}</p>

<!-- Include other components with a `client:` directive to hydrate: -->
<ReactPokemonComponent client:visible />

<!-- Mix HTML with JavaScript expressions, similar to JSX: -->
<ul>
  {myFavoritePokemon.map((data) => <li>{data.name}</li>)}
</ul>

<!-- Use a template directive to build class names from multiple strings or even objects! -->
<p class:list={["add", "dynamic", {classNames: true}]} />

You can define local JavaScript variables inside of the frontmatter component script within an Astro component. You can then inject these variables into the component’s HTML template using JSX-like expressions!

Local variables can be added into the HTML using the curly braces syntax:

---
const name = "Astro";
---
<div>
  <h1>Hello {name}!</h1>  <!-- Outputs <h1>Hello Astro!</h1> -->
</div>

Local variables can be used in curly braces to pass attribute values to both HTML elements and components:

---
const name = "Astro";
---
<h1 class={name}>Attribute expressions are supported</h1>

<MyComponent templateLiteralNameAttribute={`MyNameIs${name}`} />

Local variables can be used in JSX-like functions to produce dynamically-generated HTML elements:

---
const items = ["Dog", "Cat", "Platypus"];
---
<ul>
  {items.map((item) => (
    <li>{item}</li>
  ))}
</ul>

Astro can conditionally display HTML using JSX logical operators and ternary expressions.

---
const visible = true;
---
{visible && <p>Show me!</p>}

{visible ? <p>Show me!</p> : <p>Else show me!</p>}

You can also use dynamic tags by setting a variable to an HTML tag name or a component import:

---
import MyComponent from "./MyComponent.astro";
const Element = 'div'
const Component = MyComponent;
---
<Element>Hello!</Element> <!-- renders as <div>Hello!</div> -->
<Component /> <!-- renders as <MyComponent /> -->

When using dynamic tags:

• Variable names must be capitalized. For example, use Element, not element. Otherwise, Astro will try to render your variable name as a literal HTML tag.

• Hydration directives are not supported. When using client:* hydration directives, Astro needs to know which components to bundle for production, and the dynamic tag pattern prevents this from working.

An Astro component template can render multiple elements with no need to wrap everything in a single <div> or <>, unlike JavaScript or JSX.

---
// Template with multiple elements
---
<p>No need to wrap elements in a single containing element.</p>
<p>Astro supports multiple root elements in a template.</p>

However, when using an expression to dynamically create multiple elements, you should wrap these elements inside a fragment as you would in JavaScript or JSX. Astro supports using either <Fragment> </Fragment> or the shorthand <> </>.

---
const items = ["Dog", "Cat", "Platypus"];
---
<ul>
  {items.map((item) => (
    <>
      <li>Red {item}</li>
      <li>Blue {item}</li>
      <li>Green {item}</li>
    </>
  ))}
</ul>

Fragments can also be useful to avoid wrapper elements when adding set:* directives, as in the following example:

---
const htmlString = '<p>Raw HTML content</p>';
---
<Fragment set:html={htmlString} />

Astro component syntax is a superset of HTML. It was designed to feel familiar to anyone with HTML or JSX experience, but there are a couple of key differences between .astro files and JSX.

In Astro, you use the standard kebab-case format for all HTML attributes instead of the camelCase used in JSX. This even works for class, which is not supported by React.

<div className="box" dataValue="3" />
<div class="box" data-value="3" />

In Astro, you can use standard HTML comments where JSX would use JavaScript style comments.

<!-- HTML comment syntax is valid in .astro files -->

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 Astro.props object.

---
// Usage: <GreetingHeadline greeting="Howdy" name="Partner" />
const { greeting, name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>

This component, when imported and rendered in other Astro components, layouts or pages, can be passed these props as attributes:

---
import GreetingHeadline from './GreetingHeadline.astro';
const name = "Astro"
---
<h1>Greeting Card</h1>
<GreetingHeadline greeting="Hi" name={name} />
<p>I hope you have a wonderful day!</p>

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 Astro.props.

---
interface Props {
  name: string;
  greeting?: string;
}

const { greeting = "Hello", name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>

Component props can be given default values to use when none are provided.

---
const { greeting = "Hello", name = "Astronaut" } = Astro.props;
---
<h2>{greeting}, {name}!</h2>

The <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 <slot />

---
import Header from './Header.astro';
import Logo from './Logo.astro';
import Footer from './Footer.astro';

const { title } = Astro.props
---
<div id="content-wrapper">
  <Header />
  <Logo />
  <h1>{title}</h1>
  <slot />  <!-- children will go here -->
  <Footer />
</div>

---
import Wrapper from '../components/Wrapper.astro';
---
<Wrapper title="Fred's Page">
  <h2>All about Fred</h2>
  <p>Here is some stuff about Fred.</p>
</Wrapper>

This pattern is the basis of an Astro layout component: an entire page of HTML content can be “wrapped” with <Layout></Layout> tags and sent to the Layout component to render inside of common page elements.

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.

---
import Header from './Header.astro';
import Logo from './Logo.astro';
import Footer from './Footer.astro';

const { title } = Astro.props
---
<div id="content-wrapper">
  <Header />
  <slot name="after-header"/>  <!--  children with the `slot="after-header"` attribute will go here -->
  <Logo />
  <h1>{title}</h1>
  <slot />  <!--  children without a `slot`, or with `slot="default"` attribute will go here -->
  <Footer />
  <slot name="after-footer"/>  <!--  children with the `slot="after-footer"` attribute will go here -->
</div>

---
import Wrapper from '../components/Wrapper.astro';
---
<Wrapper title="Fred's Page">
  <img src="https://my.photo/fred.jpg" slot="after-header">
  <h2>All about Fred</h2>
  <p>Here is some stuff about Fred.</p>
  <p slot="after-footer">Copyright 2022</p>
</Wrapper>

Use a 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.

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.

---
import Header from './Header.astro';
import Logo from './Logo.astro';
import Footer from './Footer.astro';

const { title } = Astro.props
---
<div id="content-wrapper">
  <Header />
  <Logo />
  <h1>{title}</h1>
  <slot>
    <p>This is my fallback content, if there is no child passed into slot</p>
  </slot>
  <Footer />
</div>

CSS <style> tags are also supported inside of the component template.

They can be used to style your components, and all style rules are automatically scoped to the component itself to prevent CSS conflicts in large apps.

---
// Your component script here!
---
<style>
  /* scoped to the component, other H1s on the page remain the same */
  h1 { color: red }
</style>

<h1>Hello, world!</h1>

📚 See our Styling Guide for more information on applying styles.

Astro components support adding client-side interactivity using standard HTML <script> tags.

Scripts can be used to add event listeners, send analytics data, play animations, and everything else JavaScript can do on the web.

<button data-confetti-button>Celebrate!</button>

<script>
  // Import npm modules.
  import confetti from 'canvas-confetti';

  // Find our component DOM on the page.
  const buttons = document.querySelectorAll('[data-confetti-button]');

  // Add event listeners to fire confetti when a button is clicked.
  buttons.forEach((button) => {
    button.addEventListener('click', () => confetti());
  });
</script>

By default, Astro processes and bundles <script> tags, adding support for importing npm modules, writing TypeScript, and more.

📚 See our Scripting Guide for more details.

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.
• Any <script> tags are left unbundled, treated as if they had is:inline.
• They can only reference assets that are in the public/ folder.

📚 Read about Astro’s built-in components.

📚 Learn about using JavaScript framework components in your Astro project.