Mast - Status Widget

Widget Showcase

See how the widget opens, selects states, uses location, and adapts to different visual styles.

Interactive Example

Customize

Try different options and see how the same widget can fit a compact navbar, a civic dashboard, or a fixed-state page.

Embed With JavaScript

Module

Create a container, import the widget module, and mount it with your Mast API key. The key is sent in the x-mast-license-key header when the widget calls Mast API endpoints.

<div id="mast-status"></div>
<script type="module">
  import { mountMastStatusWidget } from "https://www.mast.today/widgets/status/v1.js";

  mountMastStatusWidget("#mast-status", {
    licenseKey: "YOUR_MAST_API_KEY",
    apiBaseUrl: "https://www.mast.today",
    theme: "auto",
    size: "regular",
    stateSelector: "grid",
    labelMode: "terse"
  });
</script>

Auto-Mount Markup

HTML

If you prefer markup-only setup, add the widget data attributes to a container and load the module script. The widget will mount itself on page load.

<div
  data-mast-status-widget
  data-license-key="YOUR_MAST_API_KEY"
  data-api-base-url="https://www.mast.today"
  data-theme="auto"
  data-size="regular"
  data-state-selector="grid"
  data-label-mode="terse">
</div>

<script
  type="module"
  src="https://www.mast.today/widgets/status/v1.js">
</script>

Options

Config

licenseKey: Required. Your Mast API key for widget API requests.
apiBaseUrl: Optional. Defaults to https://www.mast.today.
siteBaseUrl: Optional. Controls where footer links in the widget point. Defaults to https://www.mast.today.
storageKey: Optional. Local storage key used to remember a selected state. Defaults to mast-location.
stylesheetUrl: Optional. Provide your own stylesheet URL if you do not want the default widget styles to load automatically.
theme: Optional. Use auto, light, or dark. Defaults to auto, which follows the visitor's system color scheme.
size: Optional. Use compact, regular, or large. Defaults to regular.
presentation: Optional. Use pill for the framed badge or plain for icon/text without the pill.
labelMode: Optional. Use terse for FULL or HALF, verbose for Full-staff or Half-staff, or icon for icon-only.
stateSelector: Optional. Use grid for compact state buttons or dropdown for a select menu. Defaults to grid.
stateCode: Optional. Sets the initial U.S. state, such as AZ. Visitors can still choose another state unless the widget is fixed.
fixedStateCode: Optional. Locks the widget to one state and disables the popover. Use this when a page should only show one state's status.
popover: Optional. Use false to disable the selector popover. It is automatically disabled when fixedStateCode is set.
showLocationButton: Optional. Use false to hide browser location lookup from the popover.
showLinks: Optional. Use false to hide the compact footer links in the popover.

Customization Recipes

Examples

The same script can render a broad interactive selector, a locked single-state badge, an icon-only mark, or a larger accessibility-first status label.

// Fixed Florida status, no selector popover.
mountMastStatusWidget("#florida-status", {
  licenseKey: "YOUR_MAST_API_KEY",
  fixedStateCode: "FL",
  labelMode: "verbose",
  size: "large"
});

// Tiny icon-only mark, without pill styling.
mountMastStatusWidget("#tiny-status", {
  licenseKey: "YOUR_MAST_API_KEY",
  stateCode: "AZ",
  labelMode: "icon",
  presentation: "plain",
  popover: false
});

// Interactive compact picker without footer links.
mountMastStatusWidget("#compact-picker", {
  licenseKey: "YOUR_MAST_API_KEY",
  size: "compact",
  showLinks: false
});

// Interactive picker with a dropdown instead of the state grid.
mountMastStatusWidget("#dropdown-picker", {
  licenseKey: "YOUR_MAST_API_KEY",
  stateSelector: "dropdown",
  size: "large"
});

Styling

CSS

The widget ships with default styling and can be customized with CSS variables from your page. Scope these variables to the widget container when you only want to style one instance.

#mast-status {
  --mast-widget-text: #0f172a;
  --mast-widget-muted: #64748b;
  --mast-widget-border: #dbe3ef;
  --mast-widget-control: rgba(255, 255, 255, 0.92);
  --mast-widget-surface: #ffffff;
  --mast-widget-brand: #2563eb;
  --mast-widget-shadow: rgba(15, 23, 42, 0.16);
}

You can also target the widget classes directly, including .mast-status-trigger, .mast-status-popover, .mast-status-location-button, and .mast-status-state-button.

Location Lookup

Browser

The Use my location button only runs after a visitor chooses it. It requires a secure page context, so your site should be served over HTTPS. If a visitor declines location permission, they can still choose a state from the widget grid.

If your site uses a strict Content Security Policy, allow scripts from https://www.mast.today and API connections to https://www.mast.today.

Requirements and Limits

Notes

Modern browsers: The widget is delivered as a JavaScript module, so it requires a browser with ES module support.
Secure location lookup: Browser location only works from HTTPS pages and only after the visitor grants permission.
Content Security Policy: Sites with strict CSP rules should allow script, style, and API connections to https://www.mast.today.
Page CSS: Widget styles are namespaced and loaded automatically, but they are not Shadow DOM isolated. Very broad host-page CSS rules can still affect embedded widgets.
Versioning: Use https://www.mast.today/widgets/status/v1.js for stable embeds. Future breaking changes will ship under a new versioned URL.

Need a Key?

Access

Mast widget requests use the same API key model as the Mast API. Create a developer account to get a key, then use that key in the widget options.

Get started for Free View API docs