Support for the Gatsby Slice API was added ingatsby@5.0.0.

Gatsby includes a<Slice> React component and acreateSlice action ingatsby-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 tocreateSlice via itscomponent key is also referred to as “Slice component”.

createSlice action

ThecreateSlice action from thecreatePages API is the first step in creating a new Slice.

<Slice> placeholder

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

Aliases

An ”alias” for a Slice is the string value a page will use to identify which Slice component to render. The reasonalias is used (as opposed toid fromcreateSlice) is an alias is a one-to-one mapping for each page created. By default, analias is always created for eachid given increateSlice. Therefore, if the Slice placeholder is given analias prop of"my-image", the Slice component with theid of"my-image" will be used.

However, if you need to customize which Slice component is utilized based on the page, you can pass analias-to-id map increatePage through theslices 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 usepage queries. By exporting agraphql query, you can query Gatsby’s data layer within the slice. Variables can be accessed from thecontext passed increateSlice.

Restrictions on using<Slice> placeholder

JSS and styled-components support

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

Must be insrc directory

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

Slice placeholders work in these files:

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

Slice placeholdersdo 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 towrapRootElement or its value can be passed directly to the Slice component (as long is it follows restrictions forother props)

Props

alias

Thealias 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

• Slices How-To Guide
• Using Gatsby Slice API with TypeScript
• Enable Slices API Optimizations