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.
Argument | Type | Description |
---|---|---|
id (Required) | string | A unique identifier for this specific Slice. See also: Aliases |
component (Required) | string | The path to the component being used as a Slice component. |
context | object | An 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.
Prop | Type | Description |
---|---|---|
alias (Required) | string | The 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: