How to Create a Custom 404 Block Using Element

Element makes it easy to create a custom Block for a “Page Not Found” page in your VOLT store. Here’s how to make a custom Block that displays a product list for your 404 page.

What is a 404 Block?

When a user tries to access a page that is not available in your VOLT store, they will see your “Page Not Found” page.

A user might land on the “Page Not Found” page when following an old link or old bookmark.

(For an overview of editing your “Page Not Found” page in VOLT’s Site Designer, please read How to Customize Your 404 Error Page in the VOLT Learning Center.)

This page is also called a “404 page” because of the HTML code (“404”) returned by the server when a page is not found.

The built-in Blocks are useful for editing your “Page Not Found” page, but you may want to add additional functionality or a different design to this page.

Thankfully, it is easy to make a custom 404 Block for your VOLT store using Element.

This tutorial will demonstrate making a custom 404 Block that lists all the products for sale in your VOLT store.

Making a Custom 404 Block That Lists All products

This article assumes you know the basics of creating and publishing an Element Block. If you have never made a custom Element Block or would like a refresher, please read the 15-minute article “Building An Element Page Tutorial” in the Element Platform Documentation or watch the YouTube playlist “Element Tutorial | VOLT Learning Center” (27 minutes total playtime).

You should be authorized to develop Blocks before beginning this tutorial. For instructions, please see “How To Get Approved To Develop Blocks” in the Element Platform Documentation.

Start a New Block Using the Element CLI

From the directory where you keep your Element Blocks, run the following terminal commands to make a new Block called “404ProductListBlock”:

element new 404ProductListBlock
cd 404ProductListBlock
npm install

Next, initialize a git repository in this directory to track your changes with the commands:

git init
git add -A
git commit -am "Initial Commit"

If you would like to publish your repository online for back-up and collaboration, such as to GitHub, now would be a good time. (Here are instructions for Adding a repository from your local computer to GitHub using GitHub Desktop.)

You should already be logged in to the Element CLI. If you are not, then use the command:

element login

The login command will prompt you for your username and password for VOLT’s Site Designer.

Configure the /local/index.js File

The first step will be to find your Tenant ID for your VOLT store. From VOLT’s Site Designer (, click on the View Live Store button at the top-right. View the page’s source code (Right-click and click View Source, or use the keyboard shortcut Ctrl+U). Search the source code for “tenant” (open Find using the keyboard shortcut Ctrl+F) and you will find several results. One might look like:

window.ElementSdk.client.configure({tenant: "5ea1e8078b7634580628ec27", apiUri: ""});

The text in the quotes after “tenant:” is your Tenant ID. In your favorite text editor or IDE (such as VS Code), open the /local/index.js file and find this line, which is typically at the top of the file:

const tenantId = '$YOUR_TENANT_ID'

Update it with your tenant from the browser source:

const tenantId = "5ea1e8078b7634580628ec27"

You may also optionally want to add in some local properties (or props) for testing how the Block will respond. If you would like to do so, replace the const localEnvPropOverrides with the following code:

const localEnvPropOverrides = {
page_not_found_heading: "Page Not Found (Local Prop)",
page_not_found_text: "Sorry, that page was not found. (Local Prop)",
product_list_heading: "All Products (Local Prop)",

Updating the Tenant ID is required, but updating the local environment props is optional. 

Update the /src/configs.js File

Open the /src/configs.js file in your text editor or IDE.

Replace the entire file with the following code:

import { ElementPropTypes } from "@volusion/element-proptypes"
export const configSchema = {
page_not_found_heading: {
label: "Page Not Found Heading",
type: ElementPropTypes.string,
page_not_found_text: {
label: "Page Not Found Text Content",
type: ElementPropTypes.string,
product_list_heading: {
label: "Product List Heading",
type: ElementPropTypes.string,
export const defaultConfig = {
page_not_found_heading: "Page Not Found",
page_not_found_text: "Sorry, that page was not found.",
product_list_heading: "All Products",

This code establishes three configurable props for use in your 404 Block. These props will be editable by the user of the Block in VOLT’s Site Designer. All three props are of the “string” Element proptype. For more information, please refer to the string proptype of the Element Proptypes in the Element Platform Documentation.

Update the /src/getDataProps.js File

Open the /src/getDataProps.js file in your text editor or IDE.

Replace the entire file with the following code:

export const getDataProps = (utils, props) => {
return utils.client.products
.search({ query: "" })
.then((data) => data)
.catch((e) => console.log(e))
// Note: A pageSize property can be added to limit the search results
// For example: .search({ query: "", pageSize: 100 })

This code will retrieve all products in a single data object that will be retrieved from your VOLT store. This data object will contain all the products in a property called items, which will be an array you can access from inside your Block. Note that getDataProps should return a Promise.

Update the /src/Block.js File

Open the /src/Block.js file in your text editor or IDE.

Replace the entire file with the following code:

import React from "react"
import { css, StyleSheet } from "aphrodite/no-important"
import { getStyles } from "./getStyles"
import { defaultConfig } from "./configs"

const Block = (props) => {
const classes = StyleSheet.create(getStyles(props))
const products =

// Sort products by name if any products exist
products && products.sort((a, b) =>

// Destructure remaining props into separate variables
const { page_not_found_heading, page_not_found_text, product_list_heading } = props
return (
<h1 className={css(classes.example)}>{page_not_found_heading}</h1>
// Only render the products list if there are products
products && (
// Destructure each item into its properties{ id, name, seo_friendlyName }) => (
<li key={id}>
<a href={"/p/" + seo_friendlyName}>{name}</a>

Block.defaultProps = defaultConfig
export default Block

This custom 404 Block will show a <h1> heading, some text content, a <h2> heading for the Product List, and the list of all products as an unordered list.

This tutorial does not cover styling the Block, other than the default “example” class (available in /src/getStyles.js). For information on customizing the CSS styles, please see Styling Your Block With CSS in the Element Platform Documentation.

Launch the Local Server to Inspect the Results

Start the local development environment using the npm run start command:

npm run start

This should open a new browser window where you can inspect the new Block. If it doesn’t, then open your browser and navigate to http://localhost:4000/ to check out the Block.

The Block should show the local props (if you defined them in /src/index.js) or the default props (from /src/configs.js) as well as a list of all the products in the VOLT store.

Troubleshooting: If the local browser window is blank when previewing a custom Block, then try debugging the Block using your browser. There may be helpful error messages in the browser’s developer console. The React Dev Tools (for Google Chrome or for Mozilla Firefox) may be helpful here. You may also have luck debugging your Block by logging messages using the Console.log() function and examining the output in the browser. Be sure to double-check the Tenant ID set in the /local/index.js file as well. 

Update the Test Files to Skip the Tests

Typically, it is a good idea to show a second terminal window to run the test suite (using the npm run test command) while you are editing the files.

In order to publish your Block to VOLT’s Site Designer, you must not have any failing tests.

This tutorial does not cover updating the tests to cover the new 404 Block, so you need to modify the test files to skip the tests.

To skip the tests, edit the /__test__/Block.spec.js file to include .skip after the describe call:

describe.skip("The Block", () => {

Add the same text to the /__test__/AMP.spec.js file:

describe.skip('The Block when loaded over AMP', () => {

This will skip all the tests for now, allowing you to publish your new Block to the Store. It is a best practice to include tests for custom Blocks to prevent bugs when making future updates.

Publish the New Block

Once you are done testing the Block, you are ready to publish the Block so that you can try it in VOLT’s Site Designer.

First, stop the local server (npm start) using Ctrl+C to terminate the running process.

In order to publish a new Block from Element to VOLT’s Site Designer, you must build the Block using the npm run build command:

npm run build

Next, you can publish the Block using the Element CLI, specifically using the element publish command with the required -n (“name”) flag to set the name of the Block:

element publish -n "404 Product List Block"

Note that the name of the Block should be in quotes. The Element CLI will prompt you to select the category that best fits this Block using the arrow keys. Choose 404 by hitting the Enter key.

You will see a warning that no image exists for “thumbnail.png” because there is not yet a thumbnail image for your Block to display in VOLT’s Site Designer.

For instructions on adding a thumbnail, please see the YouTube video How to Create a Thumbnail for Your Block | Element Tutorial | VOLT Resource Center (4 min playtime).

For more information on publishing Blocks, please see the Element CLI’s publish command.

Create a New Theme in VOLT’s Site Designer

Having published the new 404 Block, you can create a new theme to work with in VOLT’s Site Designer to try out the Block. This will give you an isolated workspace, as Themes house all the Pages in your VOLT store. You will be editing the “Page: Page Not Found” page inside the theme.

In a browser, sign in to using your developer account, then click on Site Designer in the sidebar navigation on the left-hand side of the screen. (If you are already logged in, you can navigate directly to

Click the + Create new theme link in Site Designer (to the right of Inactive Themes) to open a new theme. Enter “404 Block Test Theme” as the Theme Name, then click the Create button at the bottom-right of the dialog box.

If VOLT’s Site Designer opened the store’s active theme, first click Change Theme at the top-left of the screen next to your theme name. That will take you to the screen where you can create a new theme.

Editing the 404 page Inside Site Designer

Inside of VOLT’s Site Designer, browse to the special page called “Page: Page Not Found” using the drop-down menu in the top-center of the Site Designer interface.

You edit this page the same way as any other page in VOLT’s Site Designer.

In a new theme, this page will be largely empty. By default, the “Page Not Found” page shows just the Header at top and the Footer at bottom.

To add the new custom 404 Block to the “Page Not Found” page, first click the plus sign (+) above where it says Add Block, then click 404 in the sidebar that appears at the left.

Find the name of the Block that you entered when running the element publish command with the -n “Name” flag.

Click Add Block to add the custom Block. To change the text in the custom Block, click on the newly-added Block to select it for editing.

You can preview the new “Page Not Found” page using the Preview button at the top-left of VOLT’s Site Designer, which will take you to a preview version of the VOLT store, such as: 

The Publish button in VOLT’s Site Designer will not yet publish the custom Block, because it is still in “Staging” (or development) and has not yet been “released” to production.

The next sections cover how to make changes to the custom 404 Block and how to release the new Block to public sites.

Updating the Block When You Make Changes

When you have made changes to your custom 404 Block that you are ready to launch to VOLT’s Site Designer, you need to rebuild the Block and then deploy it using the element update command:

npm run build
element update

This will make a new minor version, which will automatically update the Block inside VOLT’s Site Designer as well as in all VOLT stores using that Block. For more information, please see How To Release A Minor Version.

It is recommended to track minor version numbers using git:

git commit -am "Version 1.1"
git tag 1.1

If you would like to go back to the last minor version, you can use the element rollback command, which rolls the Block back to the previous minor version:

element rollback

Be sure to reset your git repository to that version to avoid confusion while developing by using the git reset --hard and git revert commands with the tag name:

git reset --hard 1.0
git revert 1.0

For more information on rolling back to a previous minor version, please read Rollback A Block Change in the Element Platform Documentation.

Releasing the Block to Production

Up until this point, the Block has been in Staging, meaning the Block is only visible on the preview version of your store in VOLT’s Site Designer. To make the Block live on your public store, you need to release the Block using the element release command with the -n “Notes” flag:

element release -n "Release Notes for this Version"

Note that the release notes should be in quotes.

This command will ask you to confirm using text input “Y” for yes or “n” for no, because non-major version changes will take effect immediately on the stores that have your Block installed. Release notes are optional but highly recommended.

You should also track the version release using git:

git commit -am "Version 1.0"
git tag 1.0

The first release command will release Version 1 of your custom Block. For more information, see the Element CLI’s release command.

Releasing a New Major Version

If you later make significant changes to the Block, you should create a new major version using the element publish command with the -m “Major” flag in addition to the -n “Notes” flag:

element publish -m -n "Release Notes for Major Version 2"

For more information, please read Release A New Major Block Version in the Element Platform Documentation.

In Element, minor version changes are immediately deployed to all stores using that Block when they are released to production.

On the other hand, major versions need to be deployed manually on all VOLT stores using that Block after they are released to production.

For more information, please see How To Track Block Versions in the Element Platform Documentation.


A “Page Not Found” page is crucial for all websites, since pages move and change over time. If a user finds a broken page link, a bad “Page Not Found” page could cost you a sale.

The custom 404 Block in this article lets you display a list of all Products on your site on your “Page Not Found” page. Showing a list of products may help your customer find what they were looking for.

This 404 Block can be combined with any other Blocks, built-in or custom, to improve the usefulness of your “Page Not Found” page.

Other custom 404 Blocks that might be useful include:

  • A list of the most popular products
  • A list of the products currently on sale
  • A search function
  • An email newsletter sign-up
  • An automatically-generated list of all pages on the site.

Any of these custom Blocks could be built using Element in order to add functionality to your VOLT store.