Frequently Asked Questions

Find answers to common questions about pm7-ui. Can't find what you're looking for? Feel free to open an issue on our GitHub repository.

pm7-ui is a single package that works with all frameworks. Install it using npm or yarn:

# Using npm
npm install @pm7/core

# Using yarn
yarn add @pm7/core

Then import the CSS in your project:

// In your main JavaScript/TypeScript file
import '@pm7/core/dist/pm7.css';

That's it! You can now use pm7-ui components in React, Vue, Angular, or any other framework.

Most pm7-ui components work with CSS only. However, these components require JavaScript for interactivity:

  • Menu - For dropdown functionality
  • Dialog - For open/close behavior
  • Toast - For notifications and auto-dismiss
  • Tab Selector - For tab switching
  • Accordion - For collapsible panels
  • Tooltip - For hover tooltips

When using these components, make sure to import the JavaScript:

import { PM7Menu, PM7Dialog, PM7Toast, PM7Accordion, PM7Tooltip } from '@pm7/core';

pm7-ui components can be customized in several ways:

1. CSS Custom Properties (Design Tokens)

:root {
  --pm7-color-primary: #your-color;
  --pm7-border-radius: 8px;
  --pm7-spacing-md: 1.5rem;
}

2. Component Variants

<button class="pm7-button pm7-button--secondary pm7-button--lg">
  Large Secondary Button
</button>

3. Custom CSS Classes

.pm7-button.custom-button {
  background: linear-gradient(45deg, #1C86EF, #0066CC);
  box-shadow: 0 4px 12px rgba(28, 134, 239, 0.3);
}

Yes! pm7-ui has comprehensive dark mode support with automatic theme detection. All components automatically adapt to dark mode. Features include:

  • Automatic detection - Respects system theme preferences
  • Theme Switch component - Built-in toggle for users
  • LocalStorage persistence - Remembers user preference
  • No flicker - Smooth transitions between themes

Add a Theme Switch to let users toggle between modes:

<!-- Basic theme switch -->
<div class="pm7-theme-switch" data-pm7-theme-switch>
  <span>Theme</span>
</div>

Or manually control dark mode:

<!-- Dark mode for entire page -->
<html class="dark">
  <!-- Your content -->
</html>

When implementing dark mode, you might see a brief flash of light mode before dark mode is applied. To prevent this, add a small script to your <head> BEFORE any stylesheets:

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <!-- Dark mode flicker prevention - MUST come before stylesheets -->
  <script>
    (function() {
      const savedTheme = localStorage.getItem('pm7-theme');
      if (savedTheme === 'dark' || (!savedTheme && window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
        document.documentElement.classList.add('dark');
      }
    })();
  </script>
  
  <!-- Your stylesheets come AFTER the script -->
  <link rel="stylesheet" href="@pm7/core/dist/pm7.css">
</head>

This script runs synchronously before the page renders, eliminating any flicker.

Yes! pm7-ui's dark mode colors can be customized using CSS variables. Override them in your stylesheet:

.dark {
  /* Background colors */
  --pm7-background: #0a0a0a;
  --pm7-surface: #1a1a1a;
  --pm7-muted: #262626;
  
  /* Text colors */
  --pm7-foreground: #fafafa;
  --pm7-muted-foreground: #a3a3a3;
  
  /* Primary colors */
  --pm7-primary: #3b9eff;
  --pm7-primary-foreground: #ffffff;
  
  /* Borders */
  --pm7-border: #404040;
}

All components will automatically use your custom dark mode colors.

Based on our experience implementing dark mode in pm7-ui, here are common mistakes to avoid:

  • Hardcoded colors - Using background: white or color: #000 instead of CSS variables
  • Missing link styles - Forgetting to style links, resulting in purple visited links in dark mode
  • Inline styles - Using style="background-color: #F8F9FA" which doesn't adapt to dark mode
  • Component state bugs - Not preserving CSS classes when JavaScript initializes components
  • Incomplete coverage - Only adding dark mode to some pages, not the entire site
  • Missing flicker prevention - Not adding the prevention script, causing a flash of light mode

Solution: Always use CSS variables, test every page, and follow the implementation guide in our Getting Started documentation.

pm7-ui uses a CSS-first approach with a single @pm7/core package that contains:

  • All CSS styles and design tokens
  • Vanilla JavaScript for interactive components
  • Framework-agnostic implementation

This design has several benefits:

  • Simplicity - One package to install and maintain
  • Smaller bundles - No framework-specific wrapper overhead
  • Future-proof - Works with any framework, even ones that don't exist yet
  • AI-friendly - Simple CSS classes that AI coding assistants understand

You use the same CSS classes whether you're in React, Vue, Angular, or vanilla HTML!

No, absolutely not! pm7-ui is a completely standalone component library that doesn't require any external CSS frameworks or dependencies.

pm7-ui includes:

  • Its own design system - Complete set of design tokens, colors, spacing, typography
  • Zero dependencies - Just pure CSS and vanilla JavaScript
  • Built-in styling - All components come fully styled out of the box
  • No conflicts - Works alongside any existing CSS framework if needed

This is all you need:

# Install pm7-ui
npm install @pm7/core
// Import the CSS
import '@pm7/core/dist/pm7.css';

That's it! You can now use all pm7-ui components without any additional setup or dependencies.

We welcome bug reports and feature requests! You can:

  • GitHub Issues - Open an issue on our GitHub repository
  • Pull Requests - Submit PRs for bug fixes or new features
  • Discussions - Join discussions about future development

Please include:

  • Clear description of the issue or feature
  • Steps to reproduce (for bugs)
  • Expected vs actual behavior
  • Browser and OS information

Absolutely! pm7-ui is designed to work with ANY framework. Here are examples:

<!-- Vue 3 -->
<template>
  <button class="pm7-button pm7-button--primary" @click="handleClick">
    Vue Button
  </button>
</template>

<!-- Angular -->
<button class="pm7-button pm7-button--primary" (click)="handleClick()">
  Angular Button
</button>

<!-- Svelte -->
<button class="pm7-button pm7-button--primary" on:click={handleClick}>
  Svelte Button
</button>

Just import the CSS once in your app, and you're ready to use pm7-ui components everywhere!

The entire pm7-ui library is approximately 70KB minified CSS and 10KB minified JS:

  • CSS - ~70KB minified (~12KB gzipped)
  • JavaScript - ~10KB minified (~3KB gzipped)
  • Total - ~80KB minified (~15KB gzipped)

You can reduce this by importing only the components you need.

Yes! pm7-ui includes TypeScript declarations:

  • Full type support for all components and utilities
  • IntelliSense works out of the box in VS Code and other IDEs
  • Type-safe component props and methods

TypeScript support is built-in, no additional packages needed!

pm7-ui supports all modern browsers:

  • Chrome, Firefox, Safari, Edge - Latest versions
  • iOS Safari - Version 12+
  • Chrome/Firefox on Android - Latest versions

Note: Internet Explorer is not supported.

pm7-ui works great with SSR frameworks like Next.js, Nuxt, and SvelteKit:

  • Import the CSS in your app's entry point
  • Interactive components will auto-initialize on the client side
  • No hydration issues since we use vanilla JavaScript
// Next.js example (_app.js)
import '@pm7/core/dist/pm7.css';

// Nuxt example (nuxt.config.js)
css: ['@pm7/core/dist/pm7.css']

Yes! You can use unpkg or jsDelivr:

<!-- CSS -->
<link rel="stylesheet" href="https://unpkg.com/@pm7/core/dist/pm7.css">

<!-- JavaScript (optional, only for interactive components) -->
<script src="https://unpkg.com/@pm7/core/dist/pm7.js"></script>

Or use jsDelivr for better performance:

<!-- CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@pm7/core/dist/pm7.css">

<!-- JavaScript -->
<script src="https://cdn.jsdelivr.net/npm/@pm7/core/dist/pm7.js"></script>

Currently, pm7-ui loads all CSS at once for simplicity:

  • The CSS is highly optimized and only ~70KB minified
  • Tree-shaking removes unused JavaScript automatically
  • Future version - We're considering component-level imports

For now, the small size and performance benefits of a single CSS file outweigh the complexity of per-component imports.

pm7-ui is designed to avoid conflicts:

  • Prefixed classes - All classes use the pm7- prefix
  • Works alongside Bootstrap, Tailwind, and other CSS frameworks
  • No global styles that affect non-pm7 elements

You can safely use pm7-ui in projects with existing CSS frameworks!

pm7-ui is open source under the MIT license:

  • Free for personal and commercial use
  • No attribution required (but appreciated!)
  • Can modify and distribute as needed
  • No warranty - Use at your own risk

Check the LICENSE file in our repository for full details.

To update pm7-ui to the latest version:

  1. Check the changelog for any breaking changes
  2. Update your package.json: npm update @pm7/core
  3. Test your app thoroughly

Most updates are backwards compatible, but always check the release notes!

# Update to latest version
npm update @pm7/core

# Or specify a version
npm install @pm7/core@latest

pm7-ui components emit standard DOM events and custom events:

// Menu component
const menu = document.querySelector('.pm7-menu');
menu.addEventListener('pm7-menu-select', (e) => {
  console.log('Selected:', e.detail.item);
});

// Dialog component
const dialog = document.querySelector('.pm7-dialog');
dialog.addEventListener('pm7-dialog-open', () => {
  console.log('Dialog opened');
});

Each component's documentation lists all available events.

Each component has comprehensive documentation:

  • Visit our documentation site at components
  • Each component page includes live demos, usage examples, and API reference
  • AI-friendly documentation links are available on each component page
  • You can also access raw markdown docs from our GitHub repository

Accessibility is a core priority for pm7-ui:

  • All components follow WCAG 2.1 AA guidelines
  • Full keyboard navigation support
  • Proper ARIA labels and roles
  • Screen reader tested
  • Focus management for interactive components
  • High contrast mode support

Yes! pm7-ui form components work with any validation library:

<!-- Example with native HTML5 validation -->
<input type="email" class="pm7-input" required>

<!-- Works with libraries like Yup, Zod, VeeValidate, React Hook Form, etc. -->
<!-- Just apply error classes when validation fails: -->
<input class="pm7-input pm7-input--error">
<p class="pm7-helper-text pm7-helper-text--error">Email is required</p>

Yes! You can try pm7-ui in several ways:

  • CodePen starter template: Open template
  • StackBlitz template: Open template
  • Local development: Clone our starter template from GitHub
  • Each component documentation page has live, editable examples

IF dialog not opening in React/Vue THEN check:

  1. Initialization timing - React renders AFTER DOMContentLoaded
  2. Dialog ID mismatch - Exact match required
  3. PM7 not loaded - Check window.PM7 exists

SOLUTION:

// Initialize after React render
useEffect(() => {
  window.PM7?.autoInitDialogs();
}, []);

// Open dialog
window.openDialog('my-dialog-id'); // v2.3.0+

CAUSE: PM7 state and React state are out of sync

SOLUTION: Use MutationObserver to sync states:

useEffect(() => {
  const observer = new MutationObserver(() => {
    if (dialogRef.current?.getAttribute('data-state') === 'closed' && isOpen) {
      setIsOpen(false); // Sync React state
    }
  });
  
  observer.observe(dialogRef.current, { 
    attributes: true, 
    attributeFilter: ['data-state'] 
  });
  
  return () => observer.disconnect();
}, [isOpen]);

CAUSE: PM7 transforms dialog DOM, breaking React event bindings

SOLUTION: Use global functions:

// Setup global function
useEffect(() => {
  window.handleSave = () => {
    // Your logic
    onSave();
  };
  return () => delete window.handleSave;
}, [onSave]);

// In render
<div data-pm7-footer dangerouslySetInnerHTML={{
  __html: `<button onclick="window.handleSave()">Save</button>`
}} />

SOLUTION: Since v2.3.0, dialogs auto-initialize and hide. Ensure:

  • PM7 CSS is loaded BEFORE content renders
  • Using latest version (@pm7/core@2.3.0+)
  • Not overriding PM7 dialog CSS

IF still visible THEN check CSS load order:

<!-- Load PM7 CSS first -->
<link rel="stylesheet" href="@pm7/core/dist/pm7.css">
<!-- Then your app -->
<div id="root"></div>