Installation

Installing Mod in a Astro App

How to install Mod for use in a Astro app.

To use Mod with Astro, you will want to decide how you want Mod's files loaded in your app. There are two options:

Global

This will load Mod's CSS and JavaScript globally in your app for all pages.

Global CSS and ESM JavaScript

This will load Mod's CSS globally and set up your JavaScript to load via ESM. This is the recommended approach for Astro sites.

Using Global CSS and JavaScript

To start installing Mod in your app, first, you'll want to copy the required Mod files into your app. Use the table below to know where files should go:

Paths for Plus Users

If you've purchased a copy of Mod Plus, you will want to use the plus file variants (e.g., mod-light-plus.min.css) below.

Type	File in mod(-plus).zip	Target path in app	What is it?
File	mod-light(-plus).min.css	public/mod-light(-plus).min.css	The light-themed version of Mod.
File	mod-dark(-plus).min.css	public/mod-dark(-plus).min.css	The dark-themed version of Mod.
File	mod(-plus).iife.min.js	public/mod(-plus).iife.min.js	The IIFE version of the JavaScript for Mod's interactive components. Use this if you want to load Mod's JavaScript globally in your app.
File	fonts/lucide.woff2	public/fonts/lucide.woff2	The icon font used by Mod, Lucide.
File	fonts/mod-brand-icons.woff2	public/fonts/mod-brand-icons.woff2	The icon font for brand logos used by Mod.

Once you have the files copied over to your app, next, we want to ensure that Astro always server-side renders pages in your app (vs. pre-rendering). This ensures that user changes to the theme function as intended:

astro.config.mjs

// @ts-check
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({
  output: 'server',
});

After you've updated your configuration, next, you'll want to update your src/layouts/Layout.astro file to include Mod's imports:

src/layouts/Layout.astro

---
const theme = Astro.cookies.get('theme')?.value || 'light';
---

<!doctype html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width" />
		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
		<meta name="generator" content={Astro.generator} />
		<title>Astro Basics</title>
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap" rel="stylesheet">		
  	<link rel="stylesheet" href={`/mod-${theme}(-plus).min.css`}>
		<script is:inline src="/mod(-plus).iife.min.js"></script>
	</head>
	<body data-mod-theme={theme}>
		<slot />
	</body>
</html>

<style>
	html,
	body {
		margin: 0;
		width: 100%;
		height: 100%;
		padding: 40px;
	}
</style>

Above, we begin by defining a variable in the frontmatter block for our page called theme setting it to the current value of the theme cookie in our user's browser.

Next, we include Mod's font, Inter, via a Google CDN link (optional and can be replaced with static assets in the app).

After this, depending on the theme we want to use (light or dark), we load Mod's CSS file conditionally based on the value of the theme variable we set above. In the event that the theme cookie is not set, we fall back to light as a default.

After this, we load Mod's JavaScript file (here, using the IIFE variant to enable global JavaScript). We make note to utilize Astro's is:inline directive on our script tag so Astro's preprocessing skips it (this file is already pre-bundled and optimized).

Finally, on our body tag, we set the data-mod-theme attribute to the value of our theme variable we defined (based on the theme cookie in our user's browser) using an expression data-mod-theme={theme}.

Once this is complete, Mod should be loaded globally in your Astro app. If you have a page that uses Mod components that rely on JavaScript, you can include a <script> tag in your page template:

src/pages/index.astro

---
import Welcome from '../components/Welcome.astro';
import Layout from '../layouts/Layout.astro';

// Welcome to Astro! Wondering what to do next? Check out the Astro documentation at https://docs.astro.build
// Don't want to use any of this? Delete everything in this file, the `assets`, `components`, and `layouts` directories, and start fresh.
---

<Layout>
  <div class="mod-command-palette">
    <!-- HTML for Mod's command palette component... -->
  </div>
</Layout>

<script>
document.addEventListener('DOMContentLoaded', () => {
	if (window.mod) {
		window.mod.command_palette();
	}
});
</script>

Inside of the <script> tag, we add an event listener to our document for the DOMContentLoaded event. Inside, we check to see if window.mod is defined, and if it is, call to the window.mod.command_palettte(); method.

Using Global CSS and ESM JavaScript