@docsearch/js

What is @docsearch/js?

@docsearch/js is a JavaScript library that provides a powerful and customizable search experience for documentation websites. It leverages Algolia's search capabilities to deliver fast and relevant search results.

What are @docsearch/js's main functionalities?

Basic Search Implementation

This code initializes a basic search functionality using @docsearch/js. You need to provide your Algolia API key, index name, and the selector for the input element where users will type their search queries.

const { DocSearch } = require('@docsearch/js');

const search = new DocSearch({
  apiKey: 'your-api-key',
  indexName: 'your-index-name',
  inputSelector: '#search-input',
});

search.init();

Customizing Search Results

This code demonstrates how to customize the search results by transforming the items. In this example, the titles of the search results are converted to uppercase.

const { DocSearch } = require('@docsearch/js');

const search = new DocSearch({
  apiKey: 'your-api-key',
  indexName: 'your-index-name',
  inputSelector: '#search-input',
  transformItems: (items) => {
    return items.map(item => ({
      ...item,
      title: item.title.toUpperCase(),
    }));
  }
});

search.init();

Styling the Search Interface

This code shows how to style the search interface by providing custom templates for the search items. The `templates` option allows you to define HTML templates for the search results.

const { DocSearch } = require('@docsearch/js');

const search = new DocSearch({
  apiKey: 'your-api-key',
  indexName: 'your-index-name',
  inputSelector: '#search-input',
  container: '#search-container',
  templates: {
    item: '<div class="search-item">{{title}}</div>',
  }
});

search.init();

Other packages similar to @docsearch/js

algoliasearch

The `algoliasearch` package is the official Algolia Search API client for JavaScript. It provides a more general-purpose interface for interacting with Algolia's search API, allowing you to build custom search experiences from scratch. Unlike @docsearch/js, it does not come with built-in UI components specifically designed for documentation search.

react-instantsearch

The `react-instantsearch` package is a set of React components and connectors for building search interfaces with Algolia. It offers a higher level of customization and flexibility compared to @docsearch/js, but requires more setup and knowledge of React. It is ideal for developers who want to create highly customized search experiences within React applications.

lunr

The `lunr` package is a lightweight, full-text search engine in JavaScript. It is designed to be run in the browser and does not require a server. While it does not offer the same level of performance and relevance as Algolia, it is a good alternative for smaller projects or when you want to avoid external dependencies.

README

@docsearch/js

JavaScript package for DocSearch, the best search experience for docs.

Installation

yarn add @docsearch/js@3
# or
npm install @docsearch/js@3

Get started

If you don’t want to use a package manager, you can use a standalone endpoint:

<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>

To get started, you need a container for your DocSearch component to go in. If you don’t have one already, you can insert one into your markup:

<div id="docsearch"></div>

Then, insert DocSearch into it by calling the docsearch function and providing the container. It can be a CSS selector or an Element.

Make sure to provide a container (for example, a div), not an input. DocSearch generates a fully accessible search box for you.

import docsearch from '@docsearch/js';

import '@docsearch/css';

docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
});

Documentation

Read documentation →

Changelog

3.4.0 (2023-05-24)

Features

• implement maxResultsPerGroup prop (#1891) (f82a733)