Installation

Installing Mod in a Laravel App

How to install Mod for use in a Laravel app.

To use Mod with Laravel, 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. If you're not an advanced Laravel developer, this is the recommended approach.

Global CSS and ESM JavaScript

This will load Mod's CSS globally and set up your JavaScript to load via ESM. This is recommended for advanced Laravel developers building a production-level app that want to reduce page size.

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/assets/css/mod-light(-plus).min.css	The light-themed version of Mod.
File	mod-dark(-plus).min.css	public/assets/css/mod-dark(-plus).min.css	The dark-themed version of Mod.
File	mod(-plus).iife.min.js	public/assets/js/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, you'll want to update your resources/views/app.blade.php file to include Mod's imports:

resources/views/app.blade.php

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ config('app.name', 'Laravel') }}</title>

    @php
      $theme = $_COOKIE['theme'] ?? 'light';
    @endphp

    @vite(['resources/js/app.js'])

    <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 href="{{ asset('assets/css/' . ($theme === 'dark' ? 'mod-dark(-plus).min.css' : 'mod-light(-plus).min.css')) }}" rel="stylesheet">
    <script src="{{ asset('assets/js/mod(-plus).iife.min.js') }}"></script>
  </head>
  <body data-mod-theme="{{ $theme }}">
    @yield('content')
    @stack('scripts')
  </body>
</html>

Above, we begin by declaring an @php block, setting a variable $theme to the current value of the theme cookie received by the inbound HTTP request.

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

Next, we add the CSS include for Mod, utilizing our new $theme variable in a PHP expression passed as the href to our CSS' <link> tag. Here, we concatenate our public/assets/css path with the result of checking our $theme. If the theme is dark, we load Mod's dark theme, otherwise, we load the light theme (the default we set when assigning our $theme variable above).

After this, we include Mod's JavaScript file from public/assets/js to enable Mod's JavaScript globally.

With this, Mod should be loaded globally in your app. For pages with components that require JavaScript, calls to the specific component's JavaScript can be loaded directly in your view template's HTML:

resources/views/welcome.php

@extends('app')

@section('content')
  <div class="mod-command-palette">
    <!-- HTML for Mod command palette component... -->
  </div>
  @endsection

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

Above, we add a <script> tag to our template and inside, add an event listener for the DOMContentLoaded event. In that listener's callback, we check to see if the global window.mod value is defined, and if it is, call to the JavaScript method to enable interaction for the component(s) on our page (here, we're using the Mod Plus Command Palette component).

Using Global CSS and ESM 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/assets/css/mod-light(-plus).min.css	The light-themed version of Mod.
File	mod-dark(-plus).min.css	public/assets/css/mod-dark(-plus).min.css	The dark-themed version of Mod.
File	mod(-plus).esm.min.js	resources/js/mod(-plus).esm.min.js	The ESM version of the JavaScript for Mod's interactive components. Use this if you want to load Mod's JavaScript incrementally 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, you'll want to update your vite.config.js file to add a resolve alias for Mod's JavaScript file:

vite.config.js

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
  plugins: [
    laravel({
      input: ['resources/css/app.css', 'resources/js/app.js'],
      refresh: true,
    }),
  ],
  resolve: {
    alias: {
      '@mod(-plus)': '/resources/js/mod(-plus).esm.min.js'
    }
  }
});

With this in place, next, you'll want to update your resources/views/app.blade.php file to include Mod's imports:

resources/views/app.blade.php

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ config('app.name', 'Laravel') }}</title>

    @php
      $theme = $_COOKIE['theme'] ?? 'light';
    @endphp

    @vite(['resources/js/app.js'])

    <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 href="{{ asset('assets/css/' . ($theme === 'dark' ? 'mod-dark(-plus).min.css' : 'mod-light(-plus).min.css')) }}" rel="stylesheet">
  </head>
  <body data-mod-theme="{{ $theme }}">
    @yield('content')
    @stack('scripts')
  </body>
</html>

Above, we begin by declaring an @php block, setting a variable theme to the current value of the theme cookie received by the inbound HTTP request.

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

Next, we include the CSS include for Mod, utilizing our new $theme variable in a PHP expression passed as the href to our CSS' <link> tag. Here, we concatenate our public/assets/css path with the result of checking our $theme. If the theme is dark, we load Mod's dark theme, otherwise, we load the light theme (the default we set when assigning our $theme variable above).

With this, Mod's CSS should be loaded globally in your app. For pages with components that require JavaScript, we'll want to create a separate JavaScript file that will load Mod's JavaScript APIs:

resources/js/welcome.js

import { command_palette } from '@mod(-plus)';

document.addEventListener('DOMContentLoaded', () => {
  command_palette();
});

Above, we import the command_palette() method that will be used by our HTML template file. Here, we use the @mod-plus alias that we set up in the vite.config.js file above.

With this file created, now, we need to load this file in your view template's HTML:

resources/views/welcome.php

@extends('app')

@section('content')
@extends('app')

@section('content')
<div class="mod-command-palette">
  <!-- HTML for Mod's command palette component... -->
</div>
@endsection

@push('scripts')
  @vite(['resources/js/welcome.js'])
@endpush

Above, we add a stack directive for scripts that will match the @stack('scripts') call in the <body> tag of our app.blade.html file. Inside, we make a call to the @vite() directive, passing the path to the resources/js/welcome.js file we created above.

With this, now, Vite will load the JS file and execute the Mod code we called inside of it.