Nextra Integration

The Orama Nextra plugin provides a React-based search solution for Nextra documentation sites, with automatic indexing, highlighting, and a polished search interface.

Installation

Install the plugin using your preferred package manager:

npm install @orama/plugin-nextra

Quick Start

Add the Orama search component to your Nextra site:

pages/_app.js

import { OramaSearch } from '@orama/plugin-nextra'

function MyApp({ Component, pageProps }) {
  return (
    <>
      <OramaSearch />
      <Component {...pageProps} />
    </>
  )
}

export default MyApp

The plugin automatically indexes your content at runtime and provides instant client-side search.

Configuration

Basic Configuration

Use the default configuration for quick setup:

pages/_app.js

import { OramaSearch } from '@orama/plugin-nextra'

function MyApp({ Component, pageProps }) {
  return (
    <>
      <OramaSearch
        limitResults={30}
        boost={{
          title: 2,
          description: 1,
          content: 1
        }}
      />
      <Component {...pageProps} />
    </>
  )
}

export default MyApp

Advanced Configuration

Customize search behavior and relevance:

pages/_app.js

import { OramaSearch } from '@orama/plugin-nextra'

function MyApp({ Component, pageProps }) {
  return (
    <>
      <OramaSearch
        limitResults={50}
        boost={{
          title: 3,        // Title matches are most important
          description: 2,  // Description matches are moderately important
          content: 1       // Content matches have standard weight
        }}
      />
      <Component {...pageProps} />
    </>
  )
}

export default MyApp

Configuration Options

limitResults

number

default:30

Maximum number of search results to display. Higher values show more results but may impact performance.

boost

object

Configure relevance boosting for different content fields.

Show child attributes

boost.title

number

default:2

Boost factor for matches in document titles. Higher values prioritize title matches.

boost.description

number

default:1

Boost factor for matches in descriptions/summaries.

boost.content

number

default:1

Boost factor for matches in main content.

Component Features

The OramaSearch component provides:

Match Highlighting

Automatically highlights search terms in results

Grouped Results

Results are grouped by page for better organization

Keyboard Navigation

Full keyboard support with ⌘K/Ctrl+K shortcuts

Real-Time Search

Instant results as you type with no lag

Responsive Design

Works perfectly on all device sizes

Theme Support

Automatically matches your Nextra theme

How It Works

The plugin operates in several stages:

1. Content Indexing

When your app loads, the plugin:

Reads your Nextra page structure
Extracts content from all documentation pages
Creates an Orama search index
Stores the index in memory for fast access

2. Search Execution

When users search:

Queries are executed against the in-memory index
Results are highlighted using @orama/plugin-match-highlight
Results are grouped by document/page
Relevance is calculated using boost factors

3. Result Display

Results are displayed with:

Document title grouping
Highlighted matching terms
Content snippets
Direct navigation links

Search Index Structure

The plugin creates an index with this schema:

interface NextraOrama {
  title: string          // Page or section title
  description: string    // Page description/summary
  content: string        // Main content text
  url: string           // Page URL path
  locale: string        // Content locale (e.g., 'en-US')
}

Search UI Components

The plugin includes several React components:

OramaSearch

Main search component with input and results:

import { OramaSearch } from '@orama/plugin-nextra'

<OramaSearch
  limitResults={30}
  boost={{ title: 2, description: 1, content: 1 }}
/>

Search Input

The search input includes:

Placeholder text: “Search documentation…”
Keyboard shortcut indicator (⌘K)
Focus/blur state management
Auto-clear on navigation

Search Results

Results display with:

Grouped by page title
Highlighted matched terms
Content snippets
Click-to-navigate functionality

Branded footer showing:

Number of results found
“Powered by Orama” badge
Search performance metrics

Highlighting

The plugin uses @orama/plugin-match-highlight for intelligent highlighting:

import { searchWithHighlight } from '@orama/plugin-match-highlight'

const results = await searchWithHighlight(db, {
  term: 'search query',
  mode: 'fulltext',
  limit: 30,
  boost: {
    title: 2,
    description: 1,
    content: 1
  }
})

Highlighting features:

Exact Matches: Highlights exact term matches
Partial Matches: Highlights partial word matches
Context Preservation: Shows surrounding context
Multiple Terms: Highlights all query terms

Multi-Language Support

For multi-language Nextra sites:

pages/_app.js

import { OramaSearch } from '@orama/plugin-nextra'
import { useRouter } from 'next/router'

function MyApp({ Component, pageProps }) {
  const router = useRouter()
  const { locale } = router
  
  return (
    <>
      <OramaSearch
        key={locale}  // Re-index when locale changes
        limitResults={30}
      />
      <Component {...pageProps} />
    </>
  )
}

export default MyApp

The plugin automatically:

Detects the current locale from Next.js router
Indexes content for each locale separately
Maintains separate search indexes per language

Keyboard Shortcuts

The search component supports these keyboard shortcuts:

⌘K / Ctrl+K

shortcut

Opens or focuses the search input

ESC

shortcut

Closes the search results or clears the input

↑ / ↓

shortcut

Navigate through search results

Enter

shortcut

Navigate to the selected result

Styling

The plugin uses Nextra’s default styling with additional custom classes:

// Input styles
const inputStyles = "nx-w-full nx-px-4 nx-py-2 nx-border nx-rounded..."

// Result styles
const resultStyles = "nx-p-3 nx-hover:bg-gray-100 nx-cursor-pointer..."

// Highlight styles
const highlightStyles = "nx-bg-yellow-200 nx-font-semibold..."

Custom Styling

Override styles with CSS:

styles.css

/* Customize search input */
.orama-search-input {
  border-color: #4f46e5;
  border-radius: 8px;
}

/* Customize result items */
.orama-search-result {
  padding: 16px;
  border-bottom: 1px solid #e5e7eb;
}

/* Customize highlights */
.orama-highlight {
  background-color: #fef3c7;
  font-weight: 600;
}

Performance Optimization

The plugin is optimized for performance:

Index Creation

Indexes are created asynchronously on app load
Content is indexed in parallel when possible
Memory-efficient data structures

Search Execution

Debounced search input (waits for user to stop typing)
Efficient full-text search algorithms
Result limit prevents overwhelming the UI

Result Rendering

Virtual scrolling for large result sets
Lazy loading of result details
Efficient React rendering with keys

For sites with many pages (100+), consider increasing the limitResults cautiously to balance comprehensiveness with performance.

Advanced Usage

Custom Result Grouping

The plugin groups results by title. You can customize grouping logic:

import { groupDocumentsBy } from '@orama/plugin-nextra'

const groupedByCategory = groupDocumentsBy(results.hits, 'category')
const groupedByUrl = groupDocumentsBy(results.hits, 'url')

Manual Index Creation

For advanced use cases, create indexes manually:

import { useCreateOramaIndex } from '@orama/plugin-nextra'

function MySearchComponent() {
  const { indexes } = useCreateOramaIndex()
  
  // indexes is an object with locale keys
  // indexes['en-US'] -> Orama instance for English
  // indexes['es-ES'] -> Orama instance for Spanish
  
  // Use the indexes for custom search logic
}

Troubleshooting

Search not appearing

Ensure the OramaSearch component is included in your _app.js file and is rendered in the component tree.

// ✅ Correct placement
function MyApp({ Component, pageProps }) {
  return (
    <>
      <OramaSearch />
      <Component {...pageProps} />
    </>
  )
}

No results found

Check that:

Your Nextra pages have content to index
The router is ready (router.isReady returns true)
Content is in the expected locale

Keyboard shortcuts not working

Ensure no other components or libraries are capturing the ⌘K/Ctrl+K shortcut. The plugin uses useFocus hook to manage keyboard events.

Highlighting not working

Verify that @orama/plugin-match-highlight is installed:

npm list @orama/plugin-match-highlight

If missing, reinstall the Nextra plugin:

npm install @orama/plugin-nextra

Package Information

Package Name: @orama/plugin-nextra
Version: 3.1.18
License: Apache-2.0
Repository: github.com/oramasearch/orama

Dependencies

The plugin includes:

@orama/orama: Core search engine
@orama/plugin-match-highlight: Search result highlighting
next: Next.js framework
react & react-dom: React libraries
classnames: CSS class utilities

Requirements

Nextra 2.x or 3.x
Next.js ^14.0.0
React ^18.0.0
Node.js >= 16

Next Steps

Match Highlight Plugin

Learn about the highlighting system

Core Database

Explore the core search engine

Search Guide

Learn about search features

Full Documentation

View the complete guide

Getting Started

Core Concepts

Search

Answer Engine (RAG)

Advanced Features

Text Analysis

Plugins

Framework Integrations

Guides

​Installation

​Quick Start

​Configuration

​Basic Configuration

​Advanced Configuration

​Configuration Options

​Component Features

Match Highlighting

Grouped Results

Keyboard Navigation

Real-Time Search

Responsive Design

Theme Support

​How It Works

​1. Content Indexing

​2. Search Execution

​3. Result Display

​Search Index Structure

​Search UI Components

​OramaSearch

​Search Input

​Search Results

​Orama Footer

​Highlighting

​Multi-Language Support

​Keyboard Shortcuts

​Styling

​Custom Styling

​Performance Optimization

​Index Creation

​Search Execution

​Result Rendering

​Advanced Usage

​Custom Result Grouping

​Manual Index Creation

​Troubleshooting

​Package Information

​Dependencies

​Requirements

​Next Steps

Match Highlight Plugin

Core Database

Search Guide

Full Documentation

Build docs developers (and LLMs) love

Installation

Quick Start

Configuration

Basic Configuration

Advanced Configuration

Configuration Options

Component Features

How It Works

1. Content Indexing

2. Search Execution

3. Result Display

Search Index Structure

Search UI Components

OramaSearch

Search Input

Search Results

Orama Footer

Highlighting

Multi-Language Support

Keyboard Shortcuts

Styling

Custom Styling

Performance Optimization

Index Creation

Search Execution

Result Rendering

Advanced Usage

Custom Result Grouping

Manual Index Creation

Troubleshooting

Package Information

Dependencies

Requirements

Next Steps