The optional interactive layer

#When you need it

You only need the script when you use a component whose page shows the Needs monsoon.js badge. Everything else (dialogs, popovers, menus, tabs, toggles, accordions, forms) keeps working without it, because the browser does the work.

• Dropzone
• Dropzone compact
• Image cropper
• Avatar upload
• Image viewer
• Media gallery
• Media gallery masonry
• Before and after compare
• Compare vertical
• Signature pad
• Date picker
• Date range picker
• Combobox
• Multi select combobox
• Select (custom)
• Tags input
• Sortable list
• Kanban board
• Dual range slider
• Color picker
• Data table
• Tree view
• Tree with checkboxes
• Split panes
• Toast manager
• Password strength
• Number counter
• Textarea autosize
• Command search
• Infinite scroll
• Countdown timer
• Paste an image
• Rating input
• Autoplay carousel
• Verification code
• Authenticator app setup
• QR code
• Recovery codes
• Verify screen
• Phone number
• Magic link sent
• New password
• Sign in, centered
• Sign in, split
• Sign in, compact

Without the script, those components still render with their full styling. Only the behavior that needs JavaScript is missing, so a page never breaks while the script loads.

#Install it

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/monsooncss">
<script src="https://cdn.jsdelivr.net/npm/monsooncss/dist/monsoon.js" defer></script>

npm install monsooncss

import 'monsooncss';
import { start } from 'monsooncss/js';

start();

// or the self starting browser build
import 'monsooncss/js/browser';

#Data attributes

Each behavior is switched on with a data-m-<name> attribute. Options are more attributes with the same prefix: data-m-<name>-<option>. The script reads them when it enhances the element, so markup stays declarative and works in any template language.

<!-- copy a fixed string -->
<button class="btn" data-m-copy="npm i monsooncss">Copy</button>

<!-- copy the text of another element, with a custom confirmation label -->
<code id="key">sk_live_0000</code>
<button class="btn btn-soft" data-m-copy data-m-copy-target="#key" data-m-copy-done="Key copied">Copy key</button>

Elements added later are enhanced automatically: the script watches the document with a MutationObserver, and it runs the cleanup of a component when its element is removed. That makes it safe with server rendered fragments, client side routing and any framework that inserts markup.

#Events

Components report what happened with bubbling, cancelable DOM events named monsoon:<event>. Listen on the element or anywhere above it.

document.addEventListener('monsoon:copy', (event) => {
  console.log('copied', event.detail.text);
});

document.addEventListener('monsoon:copy-error', (event) => {
  console.warn('clipboard not available', event.detail.text);
});

Each component page with the badge lists its events under JavaScript API.

#Programmatic API

import { define, emit } from 'monsooncss/js';

// A tiny custom behavior: data-m-autofocus focuses the element once
define('autofocus', (el) => {
  el.focus();
  emit(el, 'autofocus', {});
});

#Purge and the script

The purge CLI only touches CSS, so the script and the stylesheet stay independent. Classes that a component adds at runtime are part of the component layer, which purge always keeps.

#Frequently asked questions