Using MiniSearch in React: Advanced Search and Filtering Made Easy
Voke
Posted on November 22, 2024
Table of Contents:
- What Is MiniSearch and How Does It Enhance JavaScript Filtering?
- How to Set Up a React App with MiniSearch
- Cleaning the App.jsx
- Preparing the Project: Creating a Mock Database
- Setting Up a Mock Backend with JSON Server
- Building the Frontend: Creating the BlogList Component
- Routing in React: Rendering BlogList in App.jsx
- Back to BlogList.jsx
- Displaying the Data We Fetched
- Displaying the Data We Fetched: useEffect
- Enhancing the BlogList Component with Search Functionality
- How It All Looks Like with MiniSearch
- Explaining What is Really Going On
- The Solution: Persisting MiniSearch Using useRef
- Final Code
Chapter One
What Is MiniSearch and How Does It Enhance JavaScript Filtering?
MiniSearch is a lightweight JavaScript library for full-text search within small to medium datasets. It indexes data and allows advanced search capabilities like fuzzy matching, prefix searches, ranking by relevance, and field weighting.
And by fuzzy matching, fuzzy matching means finding words or parts of words even if they are not typed exactly right. For instance, if you type "wlf" instead of "wolf", a fuzzy search will still find results that include "wolf".
And by prefix searches, prefix search looks for words or parts at the start of something. So, if you're searching for "car," a prefix search would also find "cart" or "carbonated."
These features given to us by miniSearch help us find what we are looking for even if it's not typed perfectly. Thus, making search results more accurate and helpful.
And Why do we Need it?
The first advantage it gives us is Advanced Search Features:
Traditional filtering usually matches exact values or basic patterns. MiniSearch provides more sophisticated text matching. These advanced search features can guess your mistakes, like if you type "bak" instead of "back", MiniSearch knows what you mean.
Another advantage it has over traditional filtering/ search is Relevance Ranking:
MiniSearch ranks results based on relevance, improving user experience in search-heavy applications. This ensures the most relevant results appear first. For instance, if you search for "JavaScript", the system prioritizes documents or items that mention "JavaScript" prominently or frequently, improving the overall search experience.
Now that we have that out of the way, let's create a basic React.js application and see how we use MiniSearch on the clientside.
Chapter Two
How to Set Up a React App with MiniSearch:
Ok, let's set up our project. Our project will be a blog, a blog containing blog posts of some video game titles.
And for us to set up the project, I will be using the ever-dependable vite. The text editor or IDE I will be using is the bad guy, Visual Studio code editor.
I will be setting up Vite with these prompts in the terminal. And I must say, I have already created these folders prior:
To go inside the visual_testing folder:
PS C:\Users\vawkei\Documents> cd .\visual_testing\
To go inside the building-in-public-slack folder:
PS C:\Users\vawkei\Documents\visual_testing> cd .\building-in-public-slack\
To go inside the minisearch folder:
PS C:\Users\vawkei\Documents\visual_testing\building-in-public-slack> cd .\minisearch\
To go inside the frontend folder:
PS C:\Users\vawkei\Documents\visual_testing\building-in-public-slack\minisearch> cd .\frontend\
Then in the frontend folder, I am going to install Vite, because that's where we want it to be, in our frontend folder.
I will install it with this line of code:
PS C:\Users\vawkei\Documents\visual_testing\building-in-public-slack\minisearch\frontend> npm create vite@latest .
Then it gives me options to choose from, I will be going with Javascript and React here. React as a framework and Javascript as a variant.
Once Done. I will be greeted by these:
Done. Now run:
npm install
npm run dev
Then I will install the minisearch package and the react-router-dom package. Though I won't be needing the react-router package in this tutorial:
PS C:\Users\vawkei\Documents\visual_testing\building-in-public-slack\minisearch\frontend> npm install minisearch react-router-dom
Will also install scss by running this code:
PS C:\Users\vawkei\Documents\visual_testing\building-in-public-slack\minisearch\frontend> npm install sass
Now, this is not going to have a backend. Instead, I will place the data externally, somewhere. More on that later.
So if we now start our little app by running npm run dev in the terminal, we are gonna get a response like this in the terminal:
VITE v5.4.11 ready in 332 ms
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
➜ press h + enter to show help
We will have to Follow the link (ctrl + click) on this:
http://localhost:5173/
If we ctrl + click on:
http://localhost:5173/
We gonna be greeted by a page that looks like this in the browser:
Chapter Three
Cleaning the App.jsx":
The App.jsx would look like this initially:
import { useState } from "react";
import reactLogo from "./assets/react.svg";
import viteLogo from "/vite.svg";
import "./App.css";
function App() {
const [count, setCount] = useState(0);
return (
<>
<div>
<a href="https://vite.dev" target="_blank">
<img src={viteLogo} className="logo" alt="Vite logo" />
</a>
<a href="https://react.dev" target="_blank">
<img src={reactLogo} className="logo react" alt="React logo"/>
</a>
</div>
<h1>Vite + React</h1>
<div className="card">
<button onClick={() => setCount((count) => count + 1)}>
count is {count}
</button>
<p>
Edit <code>src/App.jsx</code> and save to test HMR
</p>
</div>
<p className="read-the-docs">Click on the Vite and React logos to
learn more
</p>
</>
);
}
export default App;
And this is what is responsible for the react logo and vite logo we saw in the picture above. However, we don't want to work with the present content of App.jsx, so we gotta clean it up. After cleaning it up, the content should look like this:
function App() {
return <> </>;
}
export default App;
This will leave us with a blank screen in our browser.
Chapter Four
Preparing the Project: Creating a Mock Database:
Normally, I should be getting data from a database, superbase, firebase, or whatever. Or even an API somewhere. I will be getting my data from a json file. I am gonna call it, db.json. The file will live in a folder called data, which should be at the root of our application. The content of the db file would look like this:
{
"blogs": [
{
"title": "Wolfenstein",
"text": "Wolfenstein is a groundbreaking video game series that pioneered the first-person shooter genre. Debuting in 1981, it gained fame with Wolfenstein 3D (1992), placing players in World War II as an Allied spy battling Nazis. Known for its intense gameplay, alternate history, and stealth-action elements, the series continues to evolve with modern reboots and thrilling narratives.",
"author": "voke",
"id": "1"
},
{
"title": "Bioshock",
"text": "BioShock is a critically acclaimed video game series blending first-person shooting with deep storytelling. Set in dystopian worlds like the underwater city of Rapture and floating Columbia, it explores themes of power, morality, and free will. Known for its immersive environments, philosophical depth, and plasmid abilities, BioShock redefined narrative-driven gaming since its debut in 2007.",
"author": "ese",
"id": "2"
},
{
"id": "3550",
"author": "jite",
"title": "Doom",
"text": "Doom is a legendary first-person shooter series that revolutionized gaming with its 1993 debut. Players battle demons from Hell across Mars and Earth, armed with iconic weapons like the shotgun and BFG. Known for its fast-paced action, heavy metal soundtrack, and gory visuals, Doom remains a cornerstone of the FPS genre and a cultural phenomenon."
}
]
}
Yep! Your homeboy is a gamer.😁😁😁. And just to let you know I am dying to play these titles.
Now, Let me just run through the file real quick.
The file contains a JSON object with an array of blog entries. Each object represents a video game and has the following fields:
title: The name of the video game.
text: A brief description of the game.
author: The person who wrote the blog entry.
id: A unique identifier for each blog post. e.g: "1","2","3"
Chapter Five
Setting Up a Mock Backend with JSON Server:
To get the database up and running, we will have to go to our terminal. We can open another port in the terminal, and run this command in the terminal:
C:\Users\vawkei\Documents\visual_testing\building-in-public-slack\minisearch\frontend>npx json-server --watch data/db.json --port 8000
The response we gonna get is this:
JSON Server started on PORT :8000
Press CTRL-C to stop
Watching data/db.json...
♡⸜(˶˃ ᵕ ˂˶)⸝♡
Index:
http://localhost:8000/
Static files:
Serving ./public directory if it exists
Endpoints:
http://localhost:8000/blogs
This means that our mock server/ database is ready for action.
Chapter Six
Building the Frontend: Creating the BlogList Component:
Alright! Now I am going to go inside the src folder and in there, create a component folder. Inside the component folder, I will create another folder, call it blog. Inside the blog folder, I will create another folder called, blog-list. And inside this blog-list folder, I will create two files. BlogList.jsx and BlogList.module.scss. Won't be touching on the latter here.
Then set the BlogList component like this:
import classes from "./BlogList.module.scss";
const BlogList = () => {
return (
<div>
<h2>BlogList</h2>
</div>
);
};
export default BlogList;
Chapter Seven
Routing in React: Rendering BlogList in App.jsx:
Now that we have built the basic structure of our BlogList, we have to get it connected to the App.jsx so it can be rendered on the screen/browser. To do that, let's dive into App.jsx file, and write out this code:
import { Routes, Route, Navigate } from "react-router-dom";
import Layout from "./components/layout/Layout";
import BlogList from "./components/blog/blog-list/BlogList";
function App() {
return (
<Layout>
<Routes>
<Route path="/" element={<Navigate to="/blogs" />} />
<Route path="/blogs" element={<BlogList />} />
</Routes>
</Layout>
);
}
export default App;
Didn't touch on the Layout, since it's not useful here.
Then in the main.jsx, we will set up the Browser router there like this:
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import App from "./App.jsx";
import { BrowserRouter } from "react-router-dom";
createRoot(document.getElementById("root")).render(
<StrictMode>
<BrowserRouter>
<App />
</BrowserRouter>
</StrictMode>
);
So with all these in place, whatever happens in our App.jsx would be visible in our browser/screen now.
Chapter Eight
Back to BlogList.jsx:
Setting Up the Blog and Loading States in BlogList.jsx
In here, I am going to create some states to work with and will also fetch the blog data from our local server which is running on localhost:8000.
The first state I will create is for blogs. It will start as an empty array when the App renders and will later get updated when we receive our blog data from the mock server.
Then the second state I will create, will be for loading. It will track whether the data is still being loaded. It starts as false and can be set to true while fetching data.
Soooooooooooooooo:
import classes from "./BlogList.module.scss";
import { useState } from "react";
const BlogList = () => {
//create the blog and isLoading state.
const [blogs, setBlogs] = useState([]);
const [isLoading, setIsLoading] = useState(false);
// checking if the blog state has been filled
console.log(blogs);
//fetching the blogs from our mock database:
const fetchBlogs = async () => {
setIsLoading(true);
try {
const response = await fetch("http://localhost:8000/blogs");
if (!response.ok) {
throw new Error();
}
const data = await response.json();
console.log(data);
setBlogs(data);
} catch (error) {
const message =
error instanceof Error ? error.message : "Something went wrong";
console.log(message);
} finally {
setIsLoading(false);
}
};
return (
<div>
<h2>BlogList</h2>
</div>
);
};
export default BlogList;
Chapter Nine
Displaying the data we fetched:
Building the Jsx:
First of all, I am going to build out the jsx component. And for that, I am going to write out this below in the return part:
<div>
<h2>BlogList</h2>
<div className={classes.blogs}>
{blogs.map((blog) => {
return (
<div key={blog.id} className={classes.blog}>
<div className={classes.heading}>
<h2>{blog.title}</h2>
<p>
written by: <span>{blog.author}</span>
</p>
</div>
<div>{blog.text}</div>
</div>
);
})}
</div>
</div>
Chapter Ten
Displaying the Data We Fetched: useEffect:
Here comes useEffect:
This doesn't do much. Even though we are getting the data in our console, it ain't showing up on the screen. And for it to show up on the screen, we will need the help of one of the bad guys of react, useEffect.
What is useEffect?
According to the NetNinja, "this hook, runs a function at every render of the component. Remember, the component renders initially when it first loads, and it also happens when a state changes. It re-renders the DOM, so it can update that state (the changed state) in the browser".
Soooooooooooooooo
The function we wrote earlier to fetchBlogs, we will put it in the useEffect:
import { useEffect, useState } from "react";
import classes from "./BlogList.module.scss";
const BlogList = () => {
//create the blog and isLoading state.
const [blogs, setBlogs] = useState([]);
const [isLoading, setIsLoading] = useState(false);
// checking if the blog state has been filled
console.log(blogs);
//fetching the blogs from our mock database:
const fetchBlogs = async () => {
setIsLoading(true);
try {
const response = await fetch("http://localhost:8000/blogs");
if (!response.ok) {
throw new Error();
}
const data = await response.json();
console.log(data);
setBlogs(data);
} catch (error) {
const message =
error instanceof Error ? error.message : "Something went wrong";
console.log(message);
} finally {
setIsLoading(false);
}
};
// using the useEffect hook with the fetchBlogs function.
useEffect(() => {
fetchBlogs();
}, []);
return (
<div>
<h2>BlogList</h2>
<div className={classes.blogs}>
{blogs.map((blog) => {
return (
<div
key={blog.id}
className={classes.blog}
style={{ padding: "1rem" }}>
<div className={classes.heading}>
<h2>{blog.title}</h2>
<p>
written by: <span>{blog.author}</span>
</p>
</div>
<div>{blog.text}</div>
</div>
);
})}
</div>
</div>
);
};
export default BlogList;
This piece of code, will display, or allow me to say, render the content from our mock server in our browser. The map method there is doing some magic. What it's doing is:
The map method loops through the blogs array and creates a
for each blog entry. Here's what it does:It iterates through each blog, goes through each blog in the array, and renders its content dynamically. For each blog it goes through, it creates a
That has a blog title, blog author, and blog text. It also assigns a unique key for each blog.In our browser we should have this:
Chapter Eleven
Enhancing the BlogList Component with Search Functionality:
Then we are going to put these lines of code above our useEffect:
const handleSearch = (event) => {
setQuery(event.target.value);
if (event.target.value.trim() === "") {
return setResults([]); // Clear results if query is empty
}
console.log(event.target.value);
const searchResults = miniSearch.search(event.target.value, { fuzzy: 0.2 });
console.log("searchResults:", searchResults);
setResults(searchResults);
};
Looking like the movie Inception? Just calm down, I will explain shortly. Not the movie Omen, But Oh! Men! this is the Christopher Nolan of Mern {M.E.R.N} right here.😁😁😁
Then in the Jsx, we will code this there:
<div className={classes.search}>
<input placeholder="search" value={query} onChange={handleSearch} />
</div>
Chapter Twelve
How it all looks like with MiniSearch:
Ok, now we can render the blogs on our screen. Let's now make use of MiniSearch. The whole code will look like this:
import { useEffect, useState } from "react";
import classes from "./BlogList.module.scss";
import MiniSearch from "minisearch";
const BlogList = () => {
//create the blog and isLoading state.
const [blogs, setBlogs] = useState([]);
const [isLoading, setIsLoading] = useState(false);
//create the query and results state.
const [query, setQuery] = useState("");
const [results, setResults] = useState([]);
// checking if the blog state has been filled
console.log(blogs);
// bringing in miniSearch and createing an instance:
const miniSearch = new MiniSearch({
fields: ["title", "author", "text"],
storeFields: ["title", "author", "text"],
});
console.log("Indexed Blogs after rendering:", miniSearch.documentCount);
//fetching the blogs from our mock database:
const fetchBlogs = async () => {
setIsLoading(true);
try {
const response = await fetch("http://localhost:8000/blogs");
if (!response.ok) {
throw new Error();
}
const data = await response.json();
console.log(data);
miniSearch.removeAll();
miniSearch.addAll(data);
console.log("Indexed Blogs:", miniSearch.documentCount);
setBlogs(data);
} catch (error) {
const message =
error instanceof Error ? error.message : "Something went wrong";
console.log(message);
} finally {
setIsLoading(false);
}
};
// the search functionality:
const handleSearch = (event) => {
setQuery(event.target.value);
if (event.target.value.trim() === "") {
return setResults([]);
}
console.log(event.target.value);
const searchResults = miniSearch.search(event.target.value, { fuzzy:
0.5 });
console.log("searchResults:", searchResults);
setResults(searchResults);
};
// Conditionally displaying or search results or blogs
const displayPosts = results.length > 0 ? results : blogs;
useEffect(() => {
fetchBlogs();
}, []);
return (
<div>
<h2>BlogList</h2>
{isLoading && <p>Loading...</p>}
<div className={classes.search}>
<input placeholder="search" value={query} onChange=
{handleSearch}/>
</div>
<div className={classes.blogs}>
{displayPosts.map((blog) => {
// {blogs.map((blog) => {
return (
<div
key={blog.id}
className={classes.blog}
style={{ padding: "1rem" }}>
<div className={classes.heading}>
<h2>{blog.title}</h2>
<p>
written by: <span>{blog.author}</span>
</p>
</div>
<div>{blog.text}</div>
</div>
);
})}
</div>
</div>
);
};
export default BlogList;
Now, if we type in a word in the search input, it's meant to filter it out right? But no. It's not working. What could be wrong? hmmmm!!!
Chapter Thirteen
Explaining What is Really Going on:
The Problem: MiniSearch Resets on Re-Rendering
This part really really kicked me hard in the butt like I was a bad guy in a Jet li movie while I was on it.
Let's go:
First off, this code:
const miniSearch = new MiniSearch({
fields: ["title", "author", "text"],
storeFields: ["title", "author", "text"],
});
This code creates a new instance of MiniSearch to enable full-text search. Here's what it does:
fields: Specifies which fields (title, author, text) in the data will be indexed for searching.
storeFields: Defines which fields will be included in the search results. These fields are stored alongside the indexed data for easy retrieval.
Then this:
console.log("Indexed Blogs after rendering:", miniSearch.documentCount);
This code gives us the total number of documents that have been indexed by miniSearch after the page renders.
Now, let's go further. The page renders, and when it renders, the blog state is empty initially. We can see that courtesy of this in our code:
// checking if the blog state has been filled
console.log(blogs);
After which, we get our data using the fetchBlogs function.There is data there for real, we know there's data by looking up this code:
const data = await response.json();
console.log(data);
Now this code:
miniSearch.removeAll();
This is used to remove all previously indexed items. This is useful if you need to re-index new data or clear the current search index. We want to have a clean slate so we use it.
Then this:
miniSearch.addAll(data);
The miniSearch.addAll(data) method adds all the items in the data array to the MiniSearch index.
So after getting the data, we update blogs, by running this code:
setBlogs(data);
Once we update the blogs state, The empty blogs array gets filled with our data.
In the process, we clean up our miniSearch instance to give room for fresh data to be indexed with this code:
miniSearch.removeAll();
And we add the received data to it by running this code:
miniSearch.addAll(data);
With all these that took place, our miniSearch instance should be Loaded with data, yes it is. If you check out this line of code:
console.log("Indexed Blogs:", miniSearch.documentCount);
It shows that there is data indexed there. However, upon re-rendering the page, we lose the data because miniSearch resets. We know this because of this code:
console.log("Indexed Blogs after rendering:", miniSearch.documentCount);
And look below, this is the actual content from our console.log upon running the code when it renders.
[]
BlogList.jsx:21 Indexed Blogs after rendering: 0
BlogList.jsx:14 []
BlogList.jsx:21 Indexed Blogs after rendering: 0
BlogList.jsx:35 (3) [{…}, {…}, {…}]
BlogList.jsx:40 Indexed Blogs: 3
BlogList.jsx:35 (3) [{…}, {…}, {…}]
BlogList.jsx:40 Indexed Blogs: 3
BlogList.jsx:14 (3) [{…}, {…}, {…}]
BlogList.jsx:21 Indexed Blogs after rendering: 0
BlogList.jsx:14 (3) [{…}, {…}, {…}]
BlogList.jsx:21 Indexed Blogs after rendering: 0
Chapter Fourteen
The Solution: Persisting MiniSearch Using useRef:
To prevent miniSearch from resetting on each render, we move it to a useRef so that the same instance persists across renders. Here's how:
const miniSearchRef = useRef(
new MiniSearch({
fields: ["title", "author", "text"], // Fields to search on
storeFields: ["title", "author", "text"], // Fields to return
})
);
const miniSearch = miniSearchRef.current;
console.log("Indexed Blogs after rendering:", miniSearch.documentCount);
This code block ensures that a single instance of MiniSearch persists across renders using useRef. miniSearchRef creates and stores the MiniSearch instance.
With this useRef code, we should be home and dry.
Explaining the handleSearch function:
const handleSearch = (event) => {
setQuery(event.target.value);
if (event.target.value.trim() === "") {
return setResults([]);
}
console.log(event.target.value);
const searchResults = miniSearch.search(event.target.value, { fuzzy: 0.5 });
console.log("searchResults:", searchResults);
setResults(searchResults);
};
The handleSearch function takes in whatever the user types, it updates the state query with the user's input. (event.target.value). If the input is empty, it clears the results state and stops further processing. Then it uses miniSearch to search indexed data with fuzzy matching (allows slight mismatches). Then it updates the results' state.
Chapter Fifteen
Final Code:
So our final code in BlogList would look like this:
import { useEffect, useRef, useState } from "react";
import classes from "./BlogList.module.scss";
import MiniSearch from "minisearch";
const BlogList = () => {
//create the blog and isLoading state.
const [blogs, setBlogs] = useState([]);
const [isLoading, setIsLoading] = useState(false);
//create the query and results state.
const [query, setQuery] = useState("");
const [results, setResults] = useState([]);
// checking if the blog state has been filled
console.log(blogs);
const miniSearchRef = useRef(
new MiniSearch({
fields: ["title", "author", "text"], // Fields to search on
storeFields: ["title", "author", "text"], // Fields to return
})
);
const miniSearch = miniSearchRef.current;
console.log("Indexed Blogs after rendering:", miniSearch.documentCount);
//fetching the blogs from our mock database:
const fetchBlogs = async () => {
setIsLoading(true);
try {
const response = await fetch("http://localhost:8000/blogs");
if (!response.ok) {
throw new Error();
}
const data = await response.json();
console.log(data);
miniSearch.removeAll();
miniSearch.addAll(data);
console.log("Indexed Blogs:", miniSearch.documentCount);
setBlogs(data);
} catch (error) {
const message =
error instanceof Error ? error.message : "Something went wrong";
console.log(message);
} finally {
setIsLoading(false);
}
};
// the search functionality:
const handleSearch = (event) => {
setQuery(event.target.value);
if (event.target.value.trim() === "") {
return setResults([]);
}
console.log(event.target.value);
const searchResults = miniSearch.search(event.target.value, { fuzzy:
0.5 });
console.log("searchResults:", searchResults);
setResults(searchResults);
};
// Conditionally displaying or search results or blogs
const displayPosts = results.length > 0 ? results : blogs;
useEffect(() => {
fetchBlogs();
}, []);
return (
<div>
<h2>BlogList</h2>
{isLoading && <p>Loading...</p>}
<div className={classes.search}>
<input placeholder="search" value={query} onChange=
{handleSearch}/>
</div>
<div className={classes.blogs}>
{displayPosts.map((blog) => {
// {blogs.map((blog) => {
return (
<div
key={blog.id}
className={classes.blog}
style={{ padding: "1rem" }}>
<div className={classes.heading}>
<h2>{blog.title}</h2>
<p>
written by: <span>{blog.author}</span>
</p>
</div>
<div>{blog.text}</div>
</div>
);
})}
</div>
</div>
);
};
export default BlogList;
Chapter Sixteen
Testing it out:
Now if I type wolfenst, this is what shows:
You can see it didn't even wait for me to spell it completely before filtering it out.
Let's try out typing the critically:
Critically is not a name of a title, but it searches through our text and brings out every content that has the word critically in it. And it's safe to say that Bioshock is the only content that has critically in it.
Final Thoughts
Thank you for sticking with me through this MiniSearch journey! I truly appreciate your time and patience, and I hope this guide has been helpful in navigating and understanding how to integrate MiniSearch effectively in your Reactjs project.
About the Author
Voke Bernard is a passionate and driven M.E.R.N developer, that specializes in building dynamic React.js and Express.js applications. He is always looking to collaborate on new projects. Feel free to reach out if you are interested in working with him.
Posted on November 22, 2024
Join Our Newsletter. No Spam, Only the good stuff.
Sign up to receive the latest update from our blog.