Configuration Reference

Script Tag Attributes

Configure Reef Search by adding data attributes to the script tag:

Complete Example

<script 
  src="/reef.min.js"
  data-sitemap="/sitemap.xml"
  data-max-pages="1000"
  data-scope="main"
  data-index-actions="true"
  data-index-media="true"
  data-index-structured-data="true"
  data-index-hidden="true"
  data-actions-mode="execute"
></script>

Detailed Configuration

data-sitemap

The sitemap URL is the primary discovery mechanism for Reef Search. The crawler fetches this file on initialization.

// Default: looks for /sitemap.xml
<script src="reef.min.js"></script>

// Custom path (relative to current page)
<script src="reef.min.js" data-sitemap="sitemap-index.xml"></script>

// Absolute path
<script src="reef.min.js" data-sitemap="/docs/sitemap.xml"></script>

data-max-pages

Controls how many pages Reef Search will index. This limit prevents:

• Excessive memory usage on large sites
• Long indexing times that block the main thread
• Bandwidth exhaustion on sites with many pages

// Index only the first 100 pages
<script src="reef.min.js" data-max-pages="100"></script>

Recommended values based on site size:

data-scope

Limit indexing to a specific content area using a CSS selector. This is useful for excluding:

• Navigation menus
• Footer content
• Sidebar widgets
• Repeated elements across pages

// Only index content inside <main>
<script src="reef.min.js" data-scope="main"></script>

// Index content inside element with specific class
<script src="reef.min.js" data-scope=".content-area"></script>

// Index inside the main element or article fallback
<script src="reef.min.js" data-scope="main, article"></script>

data-actions-mode

Controls how action-type search results are handled:

// Disable action execution entirely (safer for dynamic sites)
<script src="reef.min.js" data-actions-mode="navigate-only"></script>

JavaScript API

Access the Global Reef Object

After initialization, Reef Search attaches to window.Reef:

// Access the Reef Search instance
const reef = window.Reef;

// Open the search modal programmatically
reef.open();

// Close the search modal
reef.close();

API Methods

onSelect Callback

Hook into search result selection for analytics or custom behavior:

window.Reef.onselect((result, event) => {
  console.log('Selected:', result.headingText, result.url);
  // Custom analytics tracking
  gtag('event', 'search_select', {
    search_term: result.headingText,
    target_url: result.url
  });
});

Programmatic Usage

Create a custom trigger button or integrate with existing UI:

// Custom trigger button
document.getElementById('searchButton').addEventListener('click', () => {
  window.Reef.open();
});

// Search with initial query
window.Reef.open();
setTimeout(() => {
  const input = document.querySelector('reef-host input');
  if (input) input.value = 'search terms';
  input.dispatchEvent(new Event('input'));
}, 100);

Theming

Built-in Themes

Reef Search uses a dark theme by default. The modal UI is styled via Shadow DOM for style isolation.

Custom Styling

While Shadow DOM prevents external styling, you can configure key visual properties via CSS custom properties (planned for future versions). Currently, the UI uses these internal styles:

/* Modal colors (defined in Shadow DOM) */
:host { background: rgba(5, 5, 6, 0.65); }
.panel { background: #131316; border: 1px solid #2a2a2e; }
.input { color: #edebe6; }
.result:hover { background: rgba(108, 140, 255, 0.14); }
.result mark { background: rgba(255, 214, 102, 0.22); }

Hotkeys

The default hotkey configuration:

Configuration Examples

Minimal Setup

<script src="reef.min.js"></script>

Large Documentation Site

<script 
  src="reef.min.js"
  data-sitemap="/sitemap.xml"
  data-max-pages="1000"
  data-scope="article, main"
  data-index-actions="true"
  data-index-media="true">
</script>

Blog with Hidden Content

<script 
  src="reef.min.js"
  data-sitemap="/sitemap.xml"
  data-max-pages="200"
  data-index-hidden="false" // Exclude collapsed content
  data-actions-mode="navigate-only">
</script>

Dashboard Application

<script 
  src="reef.min.js"
  data-sitemap="/sitemap.xml"
  data-max-pages="100"
  data-index-actions="true"
  data-index-media="false"
  data-actions-mode="execute">
</script>