W3cubDocs

/Astro

Scripts and Event Handling

You can add interactivity to your Astro components without using a UI framework like React, Svelte, Vue, etc. using standard HTML <script> tags. This allows you to send JavaScript to run in the browser and add functionality to your Astro components.

Client-Side Scripts

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

src/components/ConfettiButton.astro

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

Using `<script>` in Astro

In .astro files, you can add client-side JavaScript by adding one (or more) <script> tags.

In this example, adding the <Hello /> component to a page will log a message to the browser console.

src/components/Hello.astro

Script bundling

By default, <script> tags are processed by Astro.

Any imports will be bundled, allowing you to import local files or Node modules.
The processed script will be injected into your page’s <head> with type="module".
TypeScript is fully supported, including importing TypeScript files.
If your component is used several times on a page, the script will only be included once.

src/components/Example.astro

To avoid bundling the script, you can use the is:inline directive.

src/components/InlineScript.astro

📚 See our directives reference page for more information about the directives available on <script> tags.

Script loading

You may want to write your scripts as separate .js/.ts files or need to reference an external script on another server. You can do this by referencing these in a <script> tag’s src attribute.

Import local scripts

When to use this: If your script lives inside of src/.

Astro will build, optimize, and add these scripts to the page for you, following its script bundling rules.

src/components/LocalScripts.astro

Load external scripts

When to use this: If your JavaScript file lives inside of public/ or on a CDN.

To load scripts outside of your project’s src/ folder, include the is:inline directive. This approach skips the JavaScript processing, bundling, and optimizations that are provided by Astro when you import scripts as described above.

src/components/ExternalScripts.astro

Common script patterns

Handle `onclick` and other events

Some UI frameworks use custom syntax for event handling like onClick={...} (React/Preact) or @click="..." (Vue). Astro follows standard HTML more closely and does not use custom syntax for events.

Instead, you can use addEventListener in a <script> tag to handle user interactions.

src/components/AlertButton.astro

Web components with custom elements

You can create your own HTML elements with custom behavior using the Web Components standard. Defining a custom element in a .astro component allows you to build interactive components without needing a UI framework library.

In this example, we define a new <astro-heart> HTML element that tracks how many times you click the heart button and updates the <span> with the latest count.

src/components/AstroHeart.astro

There are two advantages to using a custom element here:

Instead of searching the whole page using document.querySelector(), you can use this.querySelector(), which only searches within the current custom element instance. This makes it easier to work with only the children of one component instance at a time.
Although a <script> only runs once, the browser will run our custom element’s constructor() method each time it finds <astro-heart> on the page. This means you can safely write code for one component at a time, even if you intend to use this component multiple times on a page.

📚 You can learn more about custom elements in web.dev’s Reusable Web Components guide and MDN’s introduction to custom elements.

Pass frontmatter variables to scripts

In Astro components, the code in the frontmatter between the --- fences runs on the server and is not available in the browser. To send variables from the server to the client, we need a way to store our variables and then read them when JavaScript runs in the browser.

One way to do this is to use data-* attributes to store the value of variables in your HTML output. Scripts, including custom elements, can then read these attributes using an element’s dataset property once your HTML loads in the browser.

In this example component, a message prop is stored in a data-message attribute, so the custom element can read this.dataset.message and get the value of the prop in the browser.

src/components/AstroGreet.astro

Now we can use our component multiple times and be greeted by a different message for each one.

src/pages/example.astro