PicoModal

Common errors

• ReferenceError: picoModal is not defined

  cause The `picoModal` function is not available in the current scope. This typically means the JavaScript file was not loaded, or it was loaded incorrectly (e.g., trying `import` when only a global script tag was used, or vice-versa).
  fix Ensure the `picomodal.min.js` script is correctly included in your HTML before your application script, or if using a module system, verify the import path and syntax (`import picoModal from 'picomodal';` for ESM, or `const picoModal = require('picomodal');` for CJS) is correct and the module is resolving.

• Modal does not appear when calling .show()

  cause The modal might not be attached to the DOM, or there could be a CSS conflict preventing its visibility, or the `content` option was empty.
  fix Verify that your `picoModal` call includes valid `content`. Check the browser's developer tools for any errors, and inspect the DOM to see if the modal elements (`.pico-overlay`, `.pico-modal`) are present but hidden. Ensure no global CSS is overriding `display: none` or `visibility: hidden` unexpectedly on these elements.

• Modal does not close when clicking outside or pressing Escape key

  cause The `overlayClose` or `escCloses` options might be explicitly set to `false`, or a custom event handler is preventing default behavior without calling `modal.close()`.
  fix Ensure `overlayClose: true` and `escCloses: true` are set in the `picoModal` options if you desire these behaviors. If using custom close logic, ensure `modalInstance.close()` is correctly invoked in your event handlers.

Warnings

• breaking PicoModal version 3.0.0 is a major release, implying potential breaking changes from previous 2.x versions. The project's GitHub releases page or npm changelog does not explicitly detail these changes, requiring manual inspection for migration.
  Fix: Thoroughly review your existing PicoModal implementation and test all modal functionalities after upgrading to identify and address any behavioral changes. Consult the source code differences between v2.x and v3.x if issues arise.
• deprecated The PicoModal library has not been updated since September 2016, with its latest version 3.0.0 published over nine years ago. This indicates the project is no longer actively maintained, and users should be aware that new features, bug fixes, or security updates are highly unlikely.
  Fix: For new projects, consider modern, actively maintained modal libraries. For existing projects, be prepared to fork and maintain the library yourself or plan for migration to a more current solution if security or feature needs arise.
• gotcha PicoModal might not provide native support for modern JavaScript module systems like ES Modules (ESM) without a bundler, given its age. Direct `import` statements may fail in environments expecting pure ESM.
  Fix: If using a module bundler (Webpack, Rollup, Parcel), it will likely handle CJS/UMD output correctly. If attempting native ESM in browsers or Node.js, ensure the package is transpiled or served in a compatible UMD format, or consider explicitly loading it as a global script for simpler integration.

Install

• npm install picomodal npm
• yarn add picomodal yarn
• pnpm add picomodal pnpm

Imports

• picoModal
  wrong:

  const picoModal = require('picomodal');

  correct:

  import picoModal from 'picomodal';

  While CommonJS `require` might work in Node.js environments, for browser-based module bundlers or native ESM, `import` is the standard. However, given the library's age, its primary distribution might be UMD/global script, where `picoModal` is directly available on `window`.
• picoModal (Global)
  wrong:

  import picoModal from 'picomodal'; // Will be undefined if only loaded via script tag without module system

  correct:

  <!-- Via script tag -->
  <script src="path/to/picomodal.min.js"></script>
  <script>
  picoModal('Hello');
  </script>

  Historically, PicoModal was often included as a global script, making the `picoModal` function available directly on the `window` object without explicit imports. This is the simplest way for many legacy projects.
• Modal Instance Methods
  wrong:

  picoModal.close(); // You must call methods on an *instance* of the modal

  correct:

  const modalInstance = picoModal('Content').afterClose(() => console.log('Closed'));

  The `picoModal` function returns a modal instance, which then exposes methods like `show()`, `close()`, `modalElem()`, and event handlers like `afterClose()`. These methods are not directly on the main `picoModal` function itself.

Quickstart

This quickstart demonstrates creating a PicoModal with custom content, styling, a custom close button, and event handling. It shows how to obtain a modal instance and interact with its API.

import picoModal from 'picomodal';

const myModalContent = `
  <p>This is a custom PicoModal example.</p>
  <p>It's styled with an interesting overlay color and custom button text.</p>
  <button id="closeCustomModal">Got it!</button>
`;

const modal = picoModal({
  content: myModalContent,
  overlayStyles: {
    backgroundColor: '#333',
    opacity: 0.85
  },
  modalStyles: {
    border: '2px solid #007bff',
    padding: '20px',
    borderRadius: '8px'
  },
  closeButton: false, // We'll use our custom button
  overlayClose: true // Allow closing by clicking outside
}).afterCreate(function(modalInstance) {
  // Attach event listener to our custom close button after the modal DOM is created
  const closeButton = modalInstance.modalElem().querySelector('#closeCustomModal');
  if (closeButton) {
    closeButton.addEventListener('click', () => modalInstance.close());
  }
}).afterClose(() => {
  console.log('Custom modal has been closed!');
});

// To demonstrate, let's show the modal after a short delay
setTimeout(() => {
  modal.show();
}, 1000);

// You would typically trigger this from a user action, e.g.:
// document.getElementById('openModalButton').addEventListener('click', () => modal.show());