Have you already tried using WordPress headlessly with Gatsby? If you haven’t, you might check this article around the new Gatsby source plugin for WordPress; gatsby-source-wordpress is the official source plugin introduced in March 2021 as a part of the Gatsby 3 release. It significantly improves the integration with WordPress. Also, the WordPress plugin WPGraphQL providing the GraphQL API is now available via the official WordPress repository.
With stable and maintained tools, developing Gatsby websites powered by WordPress becomes easier and more interesting. I got myself involved in this field, I co-founded (with Alexandra Spalato), and recently launched Gatsby WP Themes — a niche marketplace for developers building WordPress-powered sites with Gatsby. In this article, I would love to share my insights and, in particular, discuss the search functionality.
Search does not come out of the box, but there are many options to consider. I will focus on two distinct possibilities — taking advantage of WordPress native search (WordPress search query) vs. using Jetpack Instant Search.
Getting started
Let’s start by setting up a WordPress-powered Gatsby website. For the sake of simplicity, I will follow the getting started instructions and install the gatsby-starter-wordpress-blog starter.
gatsby new gatsby-wordpress-w-search https://github.com/gatsbyjs/gatsby-starter-wordpress-blog
This simple, bare-bone starter creates routes exclusively for individual posts and blog pages. But we can keep it that simple here. Let’s imagine that we don’t want to include pages within the search results.
For the moment, I will leave the WordPress source website as it is and pull the content from the starter author’s WordPress demo. If you use your own source, just remember that there are two plugins required on the WordPress end (both available via the plugin repository):
- WPGraphQL – a plugin that runs a GraphQL server on the WordPress instance
- WPGatsby – a plugin that modifies the WPGraphQL schema in Gatsby-specific ways (it also adds some mechanism to optimize the build process)
Setting up Apollo Client
With Gatsby, we usually either use the data from queries run on page creation (page queries) or call the useStaticQuery hook. The latter is available in components and does not allow dynamic query parameters; its role is to retrieve GraphQL data at build time. None of those two query solutions works for a user’s-initiated search. Instead, we will ask WordPress to run a search query and send us back the results. Can we send a graphQL search query? Yes! WPGraphQL provides search; you can search posts in WPGraphQL like so:
posts(where: {search: "gallery"}) { nodes { id title content }
}
In order to communicate directly with our WPGraphQL API, we will install Apollo Client; it takes care of requesting and caching the data as well as updating our UI components.
yarn add @apollo/client cross-fetch
To access Apollo Client anywhere in our component tree, we need to wrap our app with ApolloProvider. Gatsby does not expose the App component that wraps around the whole application. Instead, it provides the wrapRootElement API. It’s a part of the Gatsby Browser API and needs to be implemented in the gatsby-browser.js file located at the project’s root.
// gatsby-browser.js
import React from "react"
import fetch from "cross-fetch"
import { ApolloClient, HttpLink, InMemoryCache, ApolloProvider } from "@apollo/client"
const cache = new InMemoryCache()
const link = new HttpLink({ /* Set the endpoint for your GraphQL server, (same as in gatsby-config.js) */ uri: "https://wpgatsbydemo.wpengine.com/graphql", /* Use fetch from cross-fetch to provide replacement for server environment */ fetch
})
const client = new ApolloClient({ link, cache,
})
export const wrapRootElement = ({ element }) => ( <ApolloProvider client={client}>{element}</ApolloProvider>
)
SearchForm component
Now that we’ve set up ApolloClient, let’s build our Search component.
touch src/components/search.js src/components/search-form.js src/components/search-results.js src/css/search.css
The Search component wraps SearchForm and SearchResults
// src/components/search.js
import React, { useState } from "react"
import SearchForm from "./search-form"
import SearchResults from "./search-results" const Search = () => { const [searchTerm, setSearchTerm] = useState("") return ( <div className="search-container"> <SearchForm setSearchTerm={setSearchTerm} /> {searchTerm && <SearchResults searchTerm={searchTerm} />} </div> )
}
export default Search<SearchForm /> is a simple form with controlled input and a submit handler that sets the searchTerm state value to the user submission.
// src/components/search-form.js
import React, { useState } from "react"
const SearchForm = ({ searchTerm, setSearchTerm }) => { const [value, setValue] = useState(searchTerm) const handleSubmit = e => { e.preventDefault() setSearchTerm(value) } return ( <form role="search" onSubmit={handleSubmit}> <label htmlFor="search">Search blog posts:</label> <input id="search" type="search" value={value} onChange={e => setValue(e.target.value)} /> <button type="submit">Submit</button> </form> )
}
export default SearchFormThe SearchResults component receives the searchTerm via props, and that’s where we use Apollo Client.
For each searchTerm, we would like to display the matching posts as a list containing the post’s title, excerpt, and a link to this individual post. Our query will be like so:
const GET_RESULTS = gql` query($searchTerm: String) { posts(where: { search: $searchTerm }) { edges { node { id uri title excerpt } } } }
`We will use the useQuery hook from @apollo-client to run the GET_RESULTS query with a search variable.
// src/components/search-results.js
import React from "react"
import { Link } from "gatsby"
import { useQuery, gql } from "@apollo/client"
const GET_RESULTS = gql` query($searchTerm: String) { posts(where: { search: $searchTerm }) { edges { node { id uri title excerpt } } } }
`
const SearchResults = ({ searchTerm }) => { const { data, loading, error } = useQuery(GET_RESULTS, { variables: { searchTerm } }) if (loading) return <p>Searching posts for {searchTerm}...</p> if (error) return <p>Error - {error.message}</p> return ( <section className="search-results"> <h2>Found {data.posts.edges.length} results for {searchTerm}:</h2> <ul> {data.posts.edges.map(el => { return ( <li key={el.node.id}> <Link to={el.node.uri}>{el.node.title}</Link> </li> ) })} </ul> </section> )
}
export default SearchResults
The useQuery hook returns an object that contains loading, error, and data properties. We can render different UI elements according to the query’s state. As long as loading is truthy, we display <p>Searching posts...</p>. If loading and error are both falsy, the query has completed and we can loop over the data.posts.edges and display the results.
if (loading) return <p>Searching posts...</p>
if (error) return <p>Error - {error.message}</p>
// else
return ( //... )For the moment, I am adding the <Search /> to the layout component. (I’ll move it somewhere else a little bit later.) Then, with some styling and a visible state variable, I made it feel more like a widget, opening on click and fixed-positioned in the top right corner.
Paginated queries
Without the number of entries specified, the WPGraphQL posts query returns ten first posts; we need to take care of the pagination. WPGraphQL implements the pagination following the Relay Specification for GraphQL Schema Design. I will not go into the details; let’s just note that it is a standardized pattern. Within the Relay specification, in addition to posts.edges (which is a list of { cursor, node } objects), we have access to the posts.pageInfo object that provides:
endCursor– cursor of the last item inposts.edges,startCursor– cursor of the first item inposts.edges,hasPreviousPage– boolean for “are there more results available (backward),” andhasNextPage– boolean for “are there more results available (forward).”
We can modify the slice of the data we want to access with the additional query variables:
first– the number of returned entriesafter– the cursor we should start after
How do we deal with pagination queries with Apollo Client? The recommended approach is to use the fetchMore function, that is (together with loading, error and data) a part of the object returned by the useQuery hook.
// src/components/search-results.js
import React from "react"
import { Link } from "gatsby"
import { useQuery, gql } from "@apollo/client"
const GET_RESULTS = gql` query($searchTerm: String, $after: String) { posts(first: 10, after: $after, where: { search: $searchTerm }) { edges { node { id uri title } } pageInfo { hasNextPage endCursor } } }
`
const SearchResults = ({ searchTerm }) => { const { data, loading, error, fetchMore } = useQuery(GET_RESULTS, { variables: { searchTerm, after: "" }, }) if (loading && !data) return <p>Searching posts for {searchTerm}...</p> if (error) return <p>Error - {error.message}</p> const loadMore = () => { fetchMore({ variables: { after: data.posts.pageInfo.endCursor, }, // with notifyOnNetworkStatusChange our component re-renders while a refetch is in flight so that we can mark loading state when waiting for more results (see lines 42, 43) notifyOnNetworkStatusChange: true, }) } return ( <section className="search-results"> {/* as before */} {data.posts.pageInfo.hasNextPage && ( <button type="button" onClick={loadMore} disabled={loading}> {loading ? "Loading..." : "More results"} </button> )} </section> )
}
export default SearchResults
The first argument has its default value but is necessary here to indicate that we are sending a paginated request. Without first, pageInfo.hasNextPage will always be false, no matter the search keyword.
Calling fetchMore fetches the next slice of results but we still need to tell Apollo how it should merge the “fetch more” results with the existing cached data. We specify all the pagination logic in a central location as an option passed to the InMemoryCache constructor (in the gatsby-browser.js file). And guess what? With the Relay specification, we’ve got it covered — Apollo Client provides the relayStylePagination function that does all the magic for us.
// gatsby-browser.js
import { ApolloClient, HttpLink, InMemoryCache, ApolloProvider } from "@apollo/client"
import { relayStylePagination } from "@apollo/client/utilities"
const cache = new InMemoryCache({ typePolicies: { Query: { fields: { posts: relayStylePagination(["where"]), }, }, },
})
/* as before */
Just one important detail: we don’t paginate all posts, but instead the posts that correspond to a specific where condition. Adding ["where"] as an argument to relayStylePagination creates a distinct storage key for different search terms.
Making search persistent
Right now my Search component lives in the Layout component. It’s displayed on every page but gets unmounted every time the route changes. What if we could keep the search results while navigating? We can take advantage of the Gatsby wrapPageElement browser API to set persistent UI elements around pages.
Let’s move <Search /> from the layout component to the wrapPageElement:
// gatsby-browser.js
import Search from "./src/components/search"
/* as before */
export const wrapPageElement = ({ element }) => { return <><Search />{element}</>
}
The APIs wrapPageElement and wrapRootElement exist in both the browser and Server-Side Rendering (SSR) APIs. Gatsby recommends that we implement wrapPageElement and wrapRootElement in both gatsby-browser.js and gatsby-ssr.js. Let’s create the gatsby-ssr.js (in the root of the project) and re-export our elements:
// gatsby-ssr.js
export { wrapRootElement, wrapPageElement } from "./gatsby-browser"
I deployed a demo where you can see it in action. You can also find the code in this repo.
The wrapPageElement approach may not be ideal in all cases. Our search widget is “detached” from the layout component. It works well with the position “fixed” like in our working example or within an off-canvas sidebar like in this Gatsby WordPress theme.
But what if you want to have “persistent” search results displayed within a “classic” sidebar? In that case, you could move the searchTerm state from the Search component to a search context provider placed within the wrapRootElement:
// gatsby-browser.js
import SearchContextProvider from "./src/search-context"
/* as before */
export const wrapRootElement = ({ element }) => ( <ApolloProvider client={client}> <SearchContextProvider> {element} </SearchContextProvider> </ApolloProvider>
)
…with the SearchContextProvider defined as below:
// src/search-context.js
import React, {createContext, useState} from "react"
export const SearchContext = createContext()
export const SearchContextProvider = ({ children }) => { const [searchTerm, setSearchTerm] = useState("") return ( <SearchContext.Provider value={{ searchTerm, setSearchTerm }}> {children} </SearchContext.Provider> )
}You can see it in action in another Gatsby WordPress theme:
Note how, since Apollo Client caches the search results, we immediately get them on the route change.
Results from posts and pages
If you checked the theme examples above, you might have noticed how I deal with querying more than just posts. My approach is to replicate the same logic for pages and display results for each post type separately.
Alternatively, you could use the Content Node interface to query nodes of different post types in a single connection:
const GET_RESULTS = gql` query($searchTerm: String, $after: String) { contentNodes(first: 10, after: $after, where: { search: $searchTerm }) { edges { node { id uri ... on Page { title } ... on Post { title excerpt } } } pageInfo { hasNextPage endCursor } } }
`Going beyond the default WordPress search
Our solution seems to work but let’s remember that the underlying mechanism that actually does the search for us is the native WordPress search query. And the WordPress default search function isn’t great. Its problems are limited search fields (in particular, taxonomies are not taken into account), no fuzzy matching, no control over the order of results. Big websites can also suffer from performance issues — there is no prebuilt search index, and the search query is performed directly on the website SQL database.
There are a few WordPress plugins that enhance the default search. Plugins like WP Extended Search add the ability to include selected meta keys and taxonomies in search queries.
The Relevanssi plugin replaces the standard WordPress search with its search engine using the full-text indexing capabilities of the database. Relevanssi deactivates the default search query which breaks the WPGraphQL where: {search : …}. There is some work already done on enabling Relevanssi search through WPGraphQL; the code might not be compatible with the latest WPGraphQL version, but it seems to be a good start for those who opt for Relevanssi search.
In the second part of this article, we’ll take one more possible path and have a closer look at the premium service from Jetpack — an advanced search powered by Elasticsearch. By the way, Jetpack Instant search is the solution adopted by CSS-Tricks.
Using Jetpack Instant Search with Gatsby
Jetpack Search is a per-site premium solution by Jetpack. Once installed and activated, it will take care of building an Elasticsearch index. The search queries no longer hit the SQL database. Instead, the search query requests are sent to the cloud Elasticsearch server, more precisely to:
https://public-api.wordpress.com/rest/v1.3/sites/{your-blog-id}/search
There are a lot of search parameters to specify within the URL above. In our case, we will add the following:
filter[bool][must][0][term][post_type]=post: We only need results that are posts here, simply because our Gatsby website is limited to post. In real-life use, you might need spend some time configuring the boolean queries.size=10sets the number of returned results (maximum 20).- with
highlight_fields[0]=title, we get the title string (or a part of it) with the searchTerm within the<mark>tags. highlight_fields[0]=contentis the same as below but for the post’s content.
There are three more search parameters depending on the user’s action:
query: The search term from the search input, e.g. gallerysort: how the results should be orderer, the default is by score"score_default"(relevance) but there is also"date_asc"(newest) and"date_desc"(oldest)page_handle: something like the “after” cursor for paginated results. We only request 10 results at once, and we will have a “load more” button.
Now, let’s see how a successful response is structured:
{ total: 9, corrected_query: false, page_handle: false, // or a string it the total value > 10 results: [ { _score: 196.51814, fields: { date: '2018-11-03 03:55:09', 'title.default': 'Block: Gallery', 'excerpt.default': '', post_id: 1918, // we can configure what fields we want to add here with the query search parameters }, result_type: 'post', railcar: {/* we will not use this data */}, highlight: { title: ['Block: <mark>Gallery</mark>'], content: [ 'automatically stretch to the width of your <mark>gallery</mark>. ... A four column <mark>gallery</mark> with a wide width:', '<mark>Gallery</mark> blocks have two settings: the number of columns, and whether or not images should be cropped', ], }, }, /* more results */ ], suggestions: [], // we will not use suggestions here aggregations: [], // nor the aggregations
}The results field provides an array containing the database post IDs. To display the search results within a Gatsby site, we need to extract the corresponding post nodes (in particular their uri ) from the Gatsby data layer. My approach is to implement an instant search with asynchronous calls to the rest API and intersect the results with those of the static GraphQL query that returns all post nodes.
Let’s start by building an instant search widget that communicates with the search API. Since this is not specific to Gatsby, let’s see it in action in this Pen:
Here, useDebouncedInstantSearch is a custom hook responsible for fetching the results from the Jetpack Search API. My solution uses the awesome-debounce-promise library that allows us to take some extra care of the fetching mechanism. An instant search responds to the input directly without waiting for an explicit “Go!” from the user. If I’m typing fast, the request may change several times before even the first response arrives. Thus, there might be some unnecessary network bandwidth waste. The awesome-debounce-promise waits a given time interval (say 300ms) before making a call to an API; if there is a new call within this interval, the previous one will never be executed. It also resolves only the last promise returned from the call — this prevents the concurrency issues.
Now, with the search results available, let’s move back to Gatsby and build another custom hook:
import {useStaticQuery, graphql} from "gatsby" export const useJetpackSearch = (params) => { const { allWpPost: { nodes }, } = useStaticQuery(graphql` query AllPostsQuery { allWpPost { nodes { id databaseId uri title excerpt } } } `) const { error, loading, data } = useDebouncedInstantSearch(params) return { error, loading, data: { ...data, // map the results results: data.results.map(el => { // for each result find a node that has the same databaseId as the result field post_id const node = nodes.find(item => item.databaseId === el.fields.post_id) return { // spread the node ...node, // keep the highlight info highlight: el.highlight } }), } }
}I will call the useJetpackSearch within <SearchResults />. The Gatsby-version of <SearchResults /> is almost identical as that in the Pen above. The differences are highlighted in the code block below. The hook useDebouncedInstantSearch is replaced by useJetpackSearch (that calls the former internally). There is a Gatsby Link that replaces h2 as well as el.fields["title.default"] and el.fields["excerpt.default"] are replaced by el.title and el.excerpt.
const SearchResults = ({ params, setParams }) => { const { loading, error, data } = useJetpackSearch(params) const { searchTerm } = params if (error) { return <p>Error - {error}</p> } return ( <section className="search-results"> {loading ? ( <p className="info">Searching posts .....</p> ) : ( <> {data.total !== undefined && ( <p> Found {data.total} results for{" "} {data.corrected_query ? ( <> <del>{searchTerm}</del> <span>{data.corrected_query}</span> </> ) : ( <span>{searchTerm}</span> )} </p> )} </> )} {data.results?.length > 0 && ( <ul> {data.results.map((el) => { return ( <li key={el.id}> <Link to={el.uri}> {el.highlight.title[0] ? el.highlight.title.map((item, index) => ( <React.Fragment key={index}> {parse(item)} </React.Fragment> )) : parse(el.title)} </Link> <div className="post-excerpt"> {el.highlight.content[0] ? el.highlight.content.map((item, index) => ( <div key={index}>{parse(item)}</div> )) : parse(el.excerpt)} </div> </li> ); })} </ul> )} {data.page_handle && ( <button type="button" disabled={loading} onClick={() => setParams({ pageHandle: data.page_handle })} > {loading ? "loading..." : "load more"} </button> )} </section> )
}
You can find the complete code in this repo and see it in action in this demo. Note that I no longer source WordPress data from the generic WordPress demo used by Gatsby starter. I need to have a website with Jetpack Search activated.
Wrapping up
We’ve just seen two ways of dealing with search in headless WordPress. Besides a few Gatsby-specific technical details (like using Gatsby Browser API), you can implement both discussed approaches within other frameworks. We’ve seen how to make use of the native WordPress search. I guess that it is an acceptable solution in many cases.
But if you need something better, there are better options available. One of them is Jetpack Search. Jetpack Instant Search does a great job on CSS-Tricks and, as we’ve just seen, can work with headless WordPress as well. There are probably other ways of implementing it. You can also go further with the query configuration, the filter functionalities, and how you display the results.
The post Native Search vs. Jetpack Instant Search in Headless WordPress With Gatsby appeared first on CSS-Tricks. You can support CSS-Tricks by being an MVP Supporter.