Customizing the Ecommerce UI Template

This version of React InstantSearch has been deprecated in favor of the latest version of React InstantSearch.

As well as customizing individual UI template components, you can also customize the Ecommerce UI template’s configuration file and styling to match your needs.

Configuration

The configuration file allows you to customize some parts of the Ecommerce UI template. Use the:

• Search parameters configuration to provide raw parameters to the Algolia API.
• Autocomplete configuration to configure how Autocomplete should behave.

Search parameters

To configure the search parameters, edit the variable searchParameters in the config.tsx file:

1
2
3
4
5
6
7
8
const searchParameters = {
  hitsPerPage: 10,
  maxValuesPerFacet: 50,
  attributesToSnippet: ['description:30'],
  snippetEllipsisText: '…',
  analytics: true,
  clickAnalytics: true
}

Some search parameters are applied by default.

Autocomplete

To configure Autocomplete, edit the variable autocomplete in the config.tsx file:

1
2
3
4
5
const autocomplete = {
  placeholders: ['products', 'articles', 'faq'], // Animated input placeholders.
  debouncing: 800, // Debouncing delay for a search in in milliseconds.
  detachedMediaQuery: '(max-width: 1439px)' // Media query used to toggle the detached mode.
}

Styling

It’s easy to customize the styling of the Ecommerce UI template by modifying the default theme or creating your own.

Default theme structure

You can find all themes in styles/themes (including the default theme).

The default theme is structured as follows:

Files:

• _globals.css: imports all the required theme files: local CSS files, Tailwind base, components and utilities, Autocomplete classic theme.
• base.css: defines all the base rules such as colors (using CSS variables), headings, selection.
• utilities.css: defines all the custom Tailwind utilities such as text, layout, transition.

Folders:

• ./components: contains the utilities used for the template component’s CSS classes.
• ./widgets: contains the utilities used for the React InstantSearch widget’s CSS classes.

Customize the default theme

If you don’t want to create your own theme, you can customize the default theme by changing things such as colors (to match your brand) and text sizes.

Colors

Customize default theme colors in the base.css file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
/* ---------- Brand */
--color-brand-nebula: #5468ff;
--color-brand-black: #23263b;

/* ---------- Neutral */
--color-neutral-lightest: #f4f4f5;
--color-neutral-light: #d3d4d8;
--color-neutral-dark: #91929d;
--color-neutral-darkest: #4f5162;

/* ---------- Uranus */
--color-uranus-base: #89d9d3;

/* ---------- Venus */
--color-venus-base: #aa086c;

/* ---------- Nebula */
--color-nebula-lightest: #e8eaff;
--color-nebula-light: #7884de;
--color-nebula-dark: #3f52e8;
--color-nebula-darkest: #1e2b8e;

To create a new color, add a new entry in the colors object of the tailwind.config.js file, then define the new CSS variable you used in the base.css file.

Text

Customize the default theme text (such as body and headings) in the utilities.css file:

1
2
3
4
5
6
7
8
9
10
/* ---------- Body */
.body-regular {
  @apply font-sans text-sm;
}

.body-bold {
  @apply body-regular font-bold;
}

/* [...] */

Media queries

Customize the default theme media queries in the screens.js file:

1
2
3
4
5
6
const screens = {
  tablet: '768px',
  laptop: '1440px',
  'can-hover': { raw: '(any-hover: hover)' },
  'cannot-hover': { raw: '(any-hover: none)' }
}

These media queries are used by Tailwind for the responsive utilities and by a custom hook useTailwindScreens that allows TypeScript code to detect the device type (mobile or desktop).

Create your own theme

Make your own theme, based on the default theme structure, by:

1. Creating a new folder in the styles/themes folder
2. Update the global import in the styles/_index.css file to import your theme:

1
@import "./themes/my-own-theme/_globals.css";

Why Tailwind is used

Tailwind is a utility-first CSS framework packed with classes like flex, pt-4, text-center, and rotate-90 that can build any design without leaving the markup.

Tailwind was chosen to build the Ecommerce UI template because:

• Tailwind configuration lives in one place and can be easily modified.
• Custom utilities can be created and composed together.
• CSS classes (used in React InstantSearch widgets) can be targeted using the @apply directive.
• Tailwind’s utilities simplify the building of fully responsive interfaces.
• Mobile-first approach.

Where Tailwind is used

• Tailwind utilities are used in components and pages of the Ecommerce UI template. For example, in the footer file.
• Tailwind configuration, such as the configuration for the default font family or transition duration, in the tailwind.config.js file
• Tailwind base rules and custom utilities in the default theme folder.