Gatsby Slice API
Support for the Gatsby Slice API was added in
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.
<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 from the
createPages API is the first step in creating a new Slice.
|A unique identifier for this specific Slice. See also: Aliases|
|The path to the component being used as a Slice component.|
|An object passed to the |
<Slice> placeholder requires an
alias prop. Any additional props will be passed to the underlying component.
|The Slice component created in |
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
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
"my-image" will be used.
However, if you need to customize which Slice component is utilized based on the page, you can pass an
id map in
createPage through the
slices key. If you map
"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.
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
Restrictions on using
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
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:
Slice placeholders do not work in these files:
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.
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)
alias prop must be statically analyzable, which means it must be an inline string.
The children prop does not have any restrictions and can be used in typical fashion.
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: