🧲 Magnet

A lightweight, customizable JavaScript library for creating lead capture modals. No runtime dependencies, pure vanilla JS.

Features

• 🎯 Smart Triggers - Time-based, scroll-based, or exit intent
• 🎨 Fully Customizable - Colors, text, images, and layouts
• 📱 Responsive - Works perfectly on all devices
• ✅ Form Validation - Built-in email validation and error handling
• ⚡ Lightweight - No dependencies, pure vanilla JavaScript
• 🔄 Multiple Instances - Run multiple modals on the same page

Installation

NPM

npm install @aldoalfaro/magnet

CDN

<script src="https://cdn.jsdelivr.net/npm/@aldoalfaro/magnet@latest/dist/magnet.min.js"></script>

Quick Start

<script src="https://cdn.jsdelivr.net/npm/@aldoalfaro/magnet@latest/dist/magnet.min.js"></script>
<script>
  new Magnet({
    trigger: {
      type: 'time',
      value: 3
    },
    submit: {
      url: 'https://your-webhook-url.com'
    }
  });
</script>

Examples

Time-based Trigger

Opens after 3 seconds with default styling.

new Magnet({
  trigger: {
    type: 'time',
    value: 3
  },
  submit: {
    url: 'https://hooks.website.com/...'
  }
});

Scroll Trigger (No Backdrop)

Appears at 50% scroll in bottom-right corner without backdrop overlay.

new Magnet({
  trigger: {
    type: 'scroll',
    value: 50
  },
  submit: {
    url: 'https://hooks.website.com/...'
  },
  design: {
    position: 'bottom-right',
    backdrop: false,
    ctaColor: '#FF5722'
  },
  content: {
    title: '🎁 Special Offer!',
    introText: 'Get 20% off today.'
  }
});

Exit Intent with Image

Triggers when user moves mouse to top of viewport.

new Magnet({
  trigger: {
    type: 'exit'
  },
  submit: {
    url: 'https://hooks.website.com/...'
  },
  design: {
    imageUrl: 'https://images.unsplash.com/photo-example.jpg',
    layout: 'left',
    ctaColor: '#9C27B0'
  },
  content: {
    title: 'Download Our eBook',
    introText: 'Learn advanced techniques.'
  }
});

Custom Hidden Fields

Add tracking parameters or custom data.

new Magnet({
  trigger: { type: 'time', value: 3 },
  submit: { url: 'https://your-webhook.com' },
  customFields: {
    utm_source: 'website',
    utm_campaign: 'summer-2024'
  }
});

Configuration

Full Configuration Example

new Magnet({
  // Trigger configuration
  trigger: {
    type: 'time',           // 'time', 'scroll', 'exit'
    value: 3                // seconds for time, percentage for scroll
  },
  
  // Submission configuration
  submit: {
    url: '',                // Required: webhook/API endpoint
    format: 'formdata'      // 'formdata' or 'json'
  },
  
  // Custom hidden fields
  customFields: {
    source: 'homepage',
    campaign: 'promo'
  },
  
  // Design configuration
  design: {
    position: 'centered',   // See positions below
    backdrop: true,         // Show backdrop overlay
    imageUrl: '',           // Optional image URL
    layout: 'top',          // 'top', 'left', 'right'
    backgroundColor: '#ffffff',
    textColor: '#333333',
    ctaColor: '#007bff'
  },
  
  // Content configuration
  content: {
    title: 'Get Your Free Guide',
    introText: 'Enter your details to download',
    buttonText: 'Download Now',
    thankYouTitle: 'Thank You!',
    thankYouText: 'Check your email for the download link',
    errorMessage: 'Please fill in all fields correctly.'
  }
});

Configuration Reference

| Parameter | Possible Values | Default | Description | |-----------|----------------|---------|-------------| | Trigger | | trigger.type | 'time', 'scroll', 'exit' | 'time' | When to trigger the modal | | trigger.value | Number | 3 | Seconds for time trigger, percentage for scroll trigger | | Submit | | submit.url | String (URL) | '' | Webhook or API endpoint to submit form data | | submit.format | 'formdata', 'json' | 'formdata' | Format for submission | | Custom Fields | | customFields | Object | {} | Key-value pairs for hidden form fields | | Design | | design.position | 'centered', 'bottom-right', 'top-center', 'top-left', 'bottom-left', 'bottom-center' | 'centered' | Modal position on screen | | design.backdrop | true, false | true | Show dark overlay behind modal | | design.imageUrl | String (URL) | '' | Optional image to display in modal | | design.layout | 'top', 'left', 'right' | 'top' | Image position relative to content | | design.backgroundColor | Hex color | '#ffffff' | Modal background color | | design.textColor | Hex color | '#333333' | Text color | | design.ctaColor | Hex color | '#007bff' | Submit button color | | Content | | content.title | String | '' | Optional. Main heading text. | | content.introText | String | 'Enter your details below' | Subheading or description text | | content.buttonText | String | 'Submit' | Submit button text | | content.thankYouTitle | String | 'Thank You!' | Title shown after successful submission | | content.thankYouText | String | 'We will get back to you soon.' | Message shown after successful submission | | content.errorMessage | String | 'Please fill in all fields correctly.' | Error message for validation failures | | content.nameLabel | String | 'Name' | Label for name field | | content.emailLabel | String | 'Email' | Label for email field |

Methods

open()

Manually open the modal. Can be called multiple times.

const magnet = new Magnet({ /* config */ });
magnet.open();  // Opens the modal

close()

Programmatically close the modal.

magnet.close();

Development

# Install build tools
npm install

# Build minified version
npm run build

Made with ❤️ by Aldo Alfaro