Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

Gatsby Slice API

Support for the Gatsby Slice API was added in gatsby@5.0.0.

Gatsby includes a <Slice> React component and a createSlice action in gatsby-node to help speed up common updates across your site. By pulling out common components into separate HTML files, common components can be built separately and “stitched” together with existing pages.

The <Slice> React component is also referred to as “Slice placeholder”. The React component you pass to createSlice via its component key is also referred to as “Slice component”.

createSlice action

The createSlice action from the createPages API is the first step in creating a new Slice.

ArgumentTypeDescription
id (Required)stringA unique identifier for this specific Slice. See also: Aliases
component (Required)stringThe path to the component being used as a Slice component.
contextobjectAn object passed to the component as sliceContext.

<Slice> placeholder

The <Slice> placeholder requires an alias prop. Any additional props will be passed to the underlying component.

PropTypeDescription
alias (Required)stringThe Slice component created in gatsby-node to replace this placeholder. See also: Aliases

Aliases

An ”alias” for a Slice is the string value a page will use to identify which Slice component to render. The reason alias is used (as opposed to id from createSlice) is an alias is a one-to-one mapping for each page created. By default, an alias is always created for each id given in createSlice. Therefore, if the Slice placeholder is given an alias prop of "my-image", the Slice component with the id of "my-image" will be used.

However, if you need to customize which Slice component is utilized based on the page, you can pass an alias-to-id map in createPage through the slices key. If you map "my-image" to "my-image--dog", any time the "my-image" Slice placeholder is used, it’ll use the Slice component with the id of "my-image--dog" on that page.

Queries

Slices can use “slice queries”, just as pages can use page queries. By exporting a graphql query, you can query Gatsby’s data layer within the slice. Variables can be accessed from the context passed in createSlice.

Restrictions on using <Slice> placeholder

JSS and styled-components support

Using styled-components or JSS within Slice components is currently not supported. Alternatively, you can use emotion or normal CSS.

Must be in src directory

Slice placeholders must be used in files that are nested below your site’s top-level src directory. For example:

Slice placeholders work in these files:

  • <SITE_ROOT>/src/my-page.js
  • <SITE_ROOT>/src/components/my-component.js

Slice placeholders do not work in these files:

  • <SITE_ROOT>/other-components/other-component.js
  • <SITE_ROOT>/other-library/other-component.js

Nested Slices

Gatsby does not support nested Slice placeholders. This means if you have a high level <Layout> component as a slice component, other Slice placeholders cannot exist within that <Layout> component anywhere in the tree.

Contexts

Slice placeholders do not inherit contexts from their parent components. If a context is needed, its provider can either be added to wrapRootElement or its value can be passed directly to the Slice component (as long is it follows restrictions for other props)

Props

alias

The alias prop must be statically analyzable, which means it must be an inline string.

children

The children prop does not have any restrictions and can be used in typical fashion.

Others

Any props passed to the Slice placeholder must be serializable.

This does not work:

However, a prop that ends with (for example) a string does work:

Additional Resources

Start building today on Netlify!
Edit this page on GitHub
© 2023 Gatsby, Inc.