A powerful, production-ready search plugin that integrates Typesense with Payload CMS, providing lightning-fast, typo-tolerant search capabilities with real-time synchronization and a comprehensive theme system.
npm install typesense-search-pluginA powerful, production-ready search plugin that integrates Typesense with Payload CMS, providing lightning-fast, typo-tolerant search capabilities with real-time synchronization.
- Node.js: 22.19.0+ or 20.9.0+
- Payload CMS: 3.64.0+
- Typesense: 0.25.2+
- pnpm (recommended) or npm/yarn
``bash1. Install the plugin
pnpm add typesense-search-plugin
`typescript
// payload.config.ts
import { buildConfig } from 'payload/config'
import { typesenseSearch } from 'typesense-search-plugin'export default buildConfig({
plugins: [
typesenseSearch({
typesense: {
apiKey: 'xyz',
nodes: [{ host: 'localhost', port: 8108, protocol: 'http' }],
},
collections: {
posts: {
enabled: true,
searchFields: ['title', 'content'],
facetFields: ['category', 'status'],
displayName: 'Blog Posts',
icon: '📝',
},
},
}),
],
})
``tsx
// 4. Use the search component
import { HeadlessSearchInput } from 'typesense-search-plugin'function SearchPage() {
return (
baseUrl="http://localhost:3000"
theme="modern" // Choose from: modern, minimal, elegant, dark, colorful
placeholder="Search everything..."
onResultClick={(result) => {
console.log('Selected:', result.document)
}}
/>
)
}
// Multi-collection search
function MultiCollectionSearch() {
return (
baseUrl="http://localhost:3000"
collections={['posts', 'products']}
placeholder="Search posts & products..."
onResultClick={(result) => {
console.log('Selected:', result.document)
}}
/>
)
}
// Single collection search
function PostSearch() {
return (
baseUrl="http://localhost:3000"
collection="posts"
placeholder="Search posts..."
onResultClick={(result) => {
console.log('Selected:', result.document)
}}
/>
)
}
`✨ Features
- ⚡ Lightning Fast: Sub-millisecond search response times
- 🔍 Flexible Search: Single, multiple, or universal collection search with one component
- 🎨 Modern UI: Beautiful, responsive design with Tailwind CSS
- 🎯 Smart API Selection: Automatically chooses optimal endpoint for performance
- 🔄 Real-time Sync: Automatic synchronization with Payload CMS
- 💾 Built-in Caching: In-memory cache with configurable TTL
- 🛡️ Production Ready: Comprehensive error handling and performance optimization
- 📱 Responsive: Mobile-first design that works on all devices
📚 Documentation
For detailed documentation, visit our comprehensive docs:
- Getting Started
- Installation Guide
- Configuration
- API Reference
- Components
- Customization
- Performance
- Troubleshooting
🔧 API Endpoints
-
GET /api/search - Universal search across all collections
- GET /api/search/{collection} - Search specific collection
- POST /api/search/{collection} - Advanced search with filters
- GET /api/search/{collection}/suggest - Search suggestions
- GET /api/search/collections - Collection metadata
- GET /api/search/health - Health check🎨 Components
-
HeadlessSearchInput - Single component supporting all search patterns:
- Single Collection: collection="posts" - Direct API calls for optimal performance
- Multiple Collections: collections={['posts', 'products']} - Smart filtering with universal search
- Universal Search: No collection props - Search across all collections
- Complete UI Control: Customizable rendering with comprehensive theme system🎨 Theme System
The plugin includes a powerful theme system with 5 pre-built themes and unlimited customization:
$3
`tsx
// Modern theme (default) - Clean and professional
// Minimal theme - Flat design with minimal styling
// Elegant theme - Sophisticated with gradients
// Dark theme - Perfect for dark mode
// Colorful theme - Vibrant and modern
`$3
`tsx
const customTheme = {
theme: 'modern',
colors: {
inputBorderFocus: '#10b981',
inputBackground: '#f0fdf4',
resultsBackground: '#f0fdf4',
},
spacing: {
inputPadding: '1rem 1.25rem',
inputBorderRadius: '1.5rem',
},
enableAnimations: true,
enableShadows: true,
}
``- 5 Pre-built Themes: Modern, Minimal, Elegant, Dark, Colorful
- Unlimited Customization: Override any color, spacing, typography, or animation
- Performance Options: Disable animations/shadows for better performance
- Responsive Design: Automatic mobile optimization
- CSS Variables: Advanced styling with CSS custom properties
- TypeScript Support: Full type safety for all theme configurations
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
MIT License - see LICENSE file for details.
- Typesense for the amazing search engine
- Payload CMS for the flexible headless CMS