Searching for a Category

Overview

Category search is a common feature of any storefront. This guide will explore how to implement category search using the Merchstack API.

Before we get started, we are assuming that you have already set up your project to access the Merchstack API. If you have not, please refer to the Accessing the API section of the documentation.

Search for a Category

To search for a category, you will need to make a GraphQL query to the Merchstack API. The query will look like this:

import React from 'react'
import { useQuery, gql } from '@apollo/client'

const GET_CATEGORIES = gql`
  query GetCategories($options: CategoryListOptions) {
    categories(options: $options) {
      totalItems
      items {
        name
        isTopLevel
        id
        assignmentMethod
        navName
        slug
        breadcrumbs {
          name
          id
          slug
        }
      }
    }
  }
`

function Categories() {
  const { loading, error, data } = useQuery(GET_CATEGORIES, {
    variables: {
      options: {
        filter: {
          name: {
            eq: 'Shoes',
          },
        },
      },
    },
  })

  if (loading) return <p>Loading...</p>
  if (error) return <p>Error :(</p>

  return data.categories.items.map(({ name, id }) => (
    <div key={id}>
      <p>{name}</p>
    </div>
  ))

  return <div>Categories</div>
}

The query above will return a list of categories that match the name Shoes. If you want to return a category which contains the word shoe, you can use the following query:

import React from 'react'
import { useQuery, gql } from '@apollo/client'

const GET_CATEGORIES = gql`
  query GetCategories($options: CategoryListOptions) {
    categories(options: $options) {
      totalItems
      items {
        name
        isTopLevel
        id
        assignmentMethod
        navName
        slug
        breadcrumbs {
          name
          id
          slug
        }
      }
    }
  }
`

function Categories() {
  const { loading, error, data } = useQuery(GET_CATEGORIES, {
    variables: {
      options: {
        filter: {
          name: {
            contains: 'shoe',
          },
        },
      },
    },
  })

  if (loading) return <p>Loading...</p>
  if (error) return <p>Error :(</p>

  return data.categories.items.map(({ name, id }) => (
    <div key={id}>
      <p>{name}</p>
    </div>
  ))

  return <div>Categories</div>
}

If you want to return a category which contains the word shoe and is a top level category, you can use the following query:

import React from 'react'
import { useQuery, gql } from '@apollo/client'

const GET_CATEGORIES = gql`
  query GetCategories($options: CategoryListOptions) {
    categories(options: $options) {
      totalItems
      items {
        name
        isTopLevel
        id
        assignmentMethod
        navName
        slug
        breadcrumbs {
          name
          id
          slug
        }
      }
    }
  }
`

function Categories() {
  const { loading, error, data } = useQuery(GET_CATEGORIES, {
    variables: {
      options: {
        filter: {
          name: {
            contains: 'shoe',
          },
          isTopLevel: {
            eq: true,
          },
        },
      },
    },
  })

  if (loading) return <p>Loading...</p>
  if (error) return <p>Error :(</p>

  return data.categories.items.map(({ name, id }) => (
    <div key={id}>
      <p>{name}</p>
    </div>
  ))

  return <div>Categories</div>
}

If you want to return a category which contains the word shoe and is a top level category and has a slug of shoes, you can use the following query:

import React from 'react'
import { useQuery, gql } from '@apollo/client'

const GET_CATEGORIES = gql`
  query GetCategories($options: CategoryListOptions) {
    categories(options: $options) {
      totalItems
      items {
        name
        isTopLevel
        id
        assignmentMethod
        navName
        slug
        breadcrumbs {
          name
          id
          slug
        }
      }
    }
  }
`

function Categories() {
  const { loading, error, data } = useQuery(GET_CATEGORIES, {
    variables: {
      options: {
        filter: {
          name: {
            contains: 'shoe',
          },
          isTopLevel: {
            eq: true,
          },
          slug: {
            eq: 'shoes',
          },
        },
      },
    },
  })

  if (loading) return <p>Loading...</p>
  if (error) return <p>Error :(</p>

  return data.categories.items.map(({ name, id }) => (
    <div key={id}>
      <p>{name}</p>
    </div>
  ))

  return <div>Categories</div>
}

You can handle pagination using the skip and take arguments of the categories query. We also return the totalItems field from the categories query helpful for pagination. Below is the sample code for pagination with page numbers, next, previous, first and last buttons.

import React from 'react'
import { useQuery, gql } from '@apollo/client'

const GET_CATEGORIES = gql`
  query GetCategories($options: CategoryListOptions) {
    categories(options: $options) {
      totalItems
      items {
        name
        isTopLevel
        id
        assignmentMethod
        navName
        slug
        breadcrumbs {
          name
          id
          slug
        }
      }
    }
  }
`

function Categories() {
  const { loading, error, data } = useQuery(GET_CATEGORIES, {
    variables: {
      options: {
        take,
        skip,
        filter: {
          name: {
            contains: 'shoe',
          },
        },
      },
    },
  })

  if (loading) return <p>Loading...</p>
  if (error) return <p>Error :(</p>

  return (
    <>
      {data.categories.items.map(({ name, id }) => (
        <div key={id}>
          <p>{name}</p>
        </div>
      ))}

      <div className="flex justify-center items-center">
      <button
        className="bg-gray-200 hover:bg-gray-300 text-gray-800 font-bold py-2 px-4 rounded-l"
        onClick={() => {
          setSkip(0)
        }
      }>
        First
      </button>
      <button
        className="bg-gray-200 hover:bg-gray-300 text-gray-800 font-bold py-2 px-4 rounded-l"
        onClick={() => {
          if (skip > 0) {
            setSkip(skip - take)
          }
        }}
      >
        Previous
      </button>
      
      <p className="mr-4">Page {skip / take + 1}</p>
      
      <button
        className="bg-gray-200 hover:bg-gray-300 text-gray-800 font-bold py-2 px-4 rounded-r"
        onClick={() => {
          if (skip + take < data.categories.totalItems) {
            setSkip(skip + take)
          }
        }}
      >
        Next
      </button>

      <button
        className="bg-gray-200 hover:bg-gray-300 text-gray-800 font-bold py-2 px-4 rounded-r"
        onClick={() => {
          setSkip(data.categories.totalItems - take)
        }}
      >
        Last
      </button>
    </div>
    </>
  )
}
 
export default ProductListing

By now, you should have a good idea of how to search for a category using the Merchstack API. Below we have listed all of the operators available to you:

• String Operators
• eq
• notEq
• contains
• notContains
• in
• notIn
• regex
• inNull
• Number Operators
• eq
• gt
• gte
• lt
• lte
• between
• inNull
• Boolean Operators
• eq

More information on Categories

The categories query is a paginated query which allows you to search for categories using a variety of filters. For more information on the categories query, please refer to the GraphQL Playground -> Docs -> categories