The Problem: Spam bots fill out your contact forms, newsletter signups, and comment sections
The Solution: Hide forms from server-side rendering, show them only to real users with JavaScript
npm install astro-phantom-formsWrap any form with PhantomForm to hide it from bots:
---
import { PhantomForm } from 'astro-phantom-forms';
---
<PhantomForm mode="visible">
<!-- Your form here -->
<form action="/contact" method="post">
<input type="email" name="email" placeholder="your@email.com" />
<textarea name="message" placeholder="Your message"></textarea>
<button type="submit">Send Message</button>
</form>
</PhantomForm>Result: Bots see nothing in the HTML source. Real users see the form when they scroll to it.
- ❌ CAPTCHAs: "Click all the traffic lights"
- ❌ Honeypot fields: Extra hidden form fields
- ❌ Rate limiting: Block legitimate users too
- ❌ JavaScript challenges: Complex bot detection
- ✅ Zero SSR output: Forms don't exist in HTML source
- ✅ Client-only rendering: JavaScript required to see forms
- ✅ Progressive enhancement: Works with any framework
- ✅ Zero user friction: Humans never know it's there
The secret: Most spam bots don't execute JavaScript. They scrape HTML and find... nothing.
Stop contact form spam without user verification:
<PhantomForm mode="visible">
<form action="/api/contact" method="post">
<input type="text" name="name" required />
<input type="email" name="email" required />
<textarea name="message" required></textarea>
<button type="submit">Send Message</button>
</form>
</PhantomForm>Prevent fake email submissions:
<PhantomForm mode="idle">
<form action="/api/newsletter" method="post">
<input type="email" name="email" placeholder="Enter your email" />
<button type="submit">Subscribe</button>
</form>
</PhantomForm>Protect authentication endpoints:
<PhantomForm mode="load">
<form action="/api/login" method="post">
<input type="email" name="email" />
<input type="password" name="password" />
<button type="submit">Sign In</button>
</form>
</PhantomForm>Block comment spam:
<PhantomForm mode="visible">
<form action="/api/comments" method="post">
<textarea name="comment" placeholder="Leave a comment..."></textarea>
<button type="submit">Post Comment</button>
</form>
</PhantomForm>Control when forms appear to users:
| Mode | When Forms Load | Best For |
|---|---|---|
load |
Immediately when page loads | Critical forms (login, checkout) |
idle |
When browser is idle | Secondary forms (newsletter, feedback) |
visible |
When scrolled into view | Footer forms, below-fold content |
<!-- Load immediately for important forms -->
<PhantomForm mode="load">
<form><!-- Login form --></form>
</PhantomForm>
<!-- Load when user scrolls to it -->
<PhantomForm mode="visible">
<form><!-- Contact form --></form>
</PhantomForm>
<!-- Load during browser idle time -->
<PhantomForm mode="idle">
<form><!-- Newsletter signup --></form>
</PhantomForm>Works with all Astro-supported frameworks:
---
import { PhantomForm } from 'astro-phantom-forms';
import ContactForm from '../components/ContactForm.jsx';
---
<PhantomForm mode="visible">
<ContactForm client:load />
</PhantomForm>---
import { PhantomForm } from 'astro-phantom-forms';
import ContactForm from '../components/ContactForm.vue';
---
<PhantomForm mode="visible">
<ContactForm client:load />
</PhantomForm>---
import { PhantomForm } from 'astro-phantom-forms';
import ContactForm from '../components/ContactForm.svelte';
---
<PhantomForm mode="visible">
<ContactForm client:load />
</PhantomForm>---
import { PhantomForm } from 'astro-phantom-forms';
---
<PhantomForm mode="visible">
<form action="/submit" method="post">
<!-- Any HTML form -->
</form>
</PhantomForm>- ✅ No impact on SEO: Search engines won't see forms anyway
- ✅ Progressive enhancement: Works without JavaScript for indexing
- ✅ Semantic HTML: Forms use proper markup when rendered
- ✅ Screen reader compatible: Forms render normally for assistive tech
- ✅ Keyboard navigation: Full keyboard support maintained
- ✅ Focus management: Tab order preserved
- ✅ ARIA attributes: All accessibility features intact
- ✅ Zero bundle size: Uses native Web Components
- ✅ Lazy loading: Forms load only when needed
- ✅ No dependencies: Pure JavaScript implementation
<!-- Different hydration for different forms -->
<PhantomForm mode="load">
<form><!-- Important form loads immediately --></form>
</PhantomForm>
<PhantomForm mode="visible">
<form><!-- Secondary form loads when visible --></form>
</PhantomForm>
<PhantomForm mode="idle">
<form><!-- Background form loads when idle --></form>
</PhantomForm>---
import PhantomForm from 'astro-phantom-forms/components/PhantomForm.astro';
---
<PhantomForm mode="visible">
<form><!-- Your form --></form>
</PhantomForm>Full TypeScript definitions included:
interface Props {
mode?: 'load' | 'idle' | 'visible';
}# Run tests
npm test
# Build package
npm run build
# Local development
npm linkCheck that forms are hidden from SSR:
# View source - should show no form elements
curl -s https://yoursite.com/contact | grep -i "<form"
# Should return empty result- Astro 5.8.1 or higher
- Node.js 18+
- Modern browsers with JavaScript enabled
npm install astro-phantom-forms<!-- Named import (recommended) -->
import { PhantomForm } from 'astro-phantom-forms';
<!-- Direct import -->
import PhantomForm from 'astro-phantom-forms/components/PhantomForm.astro';| Solution | User Friction | Spam Blocking | SEO Impact | Setup Complexity |
|---|---|---|---|---|
| PhantomForm | ✅ None | ✅ Excellent | ✅ None | ✅ Minimal |
| CAPTCHA | ❌ High | ✅ Good | ❌ Negative | ❌ Complex |
| Honeypots | ✅ None | ✅ None | ||
| Rate Limiting | ✅ None | ❌ Complex | ||
| JS Challenges | ✅ Good | ❌ Complex |
Most spam bots:
- 🤖 Scrape HTML without executing JavaScript
- 🤖 Submit forms found in static HTML source
- 🤖 Don't handle client-side rendering
- 🤖 Target server-side rendered content
PhantomForm:
- 👻 Hides forms from static HTML (bots see nothing)
- 👻 Renders forms client-side (humans see everything)
- 👻 Uses Web Components (native browser support)
- 👻 Leverages Astro's islands architecture
Result: 90%+ spam reduction with zero user impact.
<!-- Before: Honeypot field -->
<form>
<input type="text" name="website" style="display:none" />
<input type="email" name="email" />
<button type="submit">Submit</button>
</form>
<!-- After: PhantomForm -->
<PhantomForm mode="visible">
<form>
<input type="email" name="email" />
<button type="submit">Submit</button>
</form>
</PhantomForm><!-- Before: CAPTCHA verification -->
<form>
<input type="email" name="email" />
<div class="captcha">
<!-- Complex CAPTCHA widget -->
</div>
<button type="submit">Submit</button>
</form>
<!-- After: PhantomForm -->
<PhantomForm mode="visible">
<form>
<input type="email" name="email" />
<button type="submit">Submit</button>
</form>
</PhantomForm>Spam Protection: Block form spam, prevent bot submissions, stop automated attacks
Astro Components: Form components, client-side rendering, islands architecture
Anti-Bot: Bot detection, spam prevention, automated protection
Web Forms: Contact forms, newsletter signups, authentication forms
JavaScript: Client-side hydration, progressive enhancement, Web Components
User Experience: No CAPTCHAs, frictionless forms, invisible protection
- 📖 Installation Guide - Detailed setup instructions
- 🔧 Examples - Real-world usage examples
- 🐛 Troubleshooting - Common issues and solutions
- 🤝 Contributing - Help improve the project
- 🐛 Bug reports: GitHub Issues
- 💬 Questions: GitHub Discussions
- 📧 Security issues: Contact privately
MIT License - see LICENSE.md for details.
Stop fighting spam. Start using stealth. 👻
Built with ❤️ for the Astro community.