Slices

What are slices?

Slices are sections of a website page — like a block of text, a hero, or a call to action. They are modeled using a collection of fields.

Content writers build website pages using a stack of slices.

Slices are created from scratch by developers. A slice’s fields are modeled by a developer during the content modeling process. A developer then builds a UI component to display when the slice is used in a page.

Developers control which slices are available to content writers. For example, a homepage might allow a Hero slice, while a blog post might allow a Quote slice. When needed, slices can be made available to multiple page types.

A slice’s files, including its model and component, are saved in the website’s code.

How to create a slice

There are two stages to creating a slice:

• Local development: Model the slice and create its UI component.
• Push to Prismic: Add it to a page type and make it available to content writers.

Local development

Start by building your slice in your local development environment. You can spend as much time as needed in this stage before making it available to content writers.

• Open Slice Machine

  In your Prismic project, start Slice Machine to begin editing content models.

  npx start-slicemachine --open

• Create a slice

  In Slice Machine, navigate to the Slices settings from the sidebar.

  Click the Create button in the top-right corner.

  

  The slice name determines the label shown to content writers in the Page Builder and the name shown to developers in the website’s code. Use an easily understood, pascal-case name.

  The target library determines which slice library the slice is added to.

• Model your content

  Use the Add a field button to add fields to the slice as needed.

  

• Add a screenshot

  Screenshots help content writers select the correct slice.

  Take a screenshot of your slice’s design. Then click the ”…” button and select Update screenshot.

  

• Create a slice component

  Every slice has a UI component to display the slice on your website.

  Slice Machine generates a basic component to get you started. Where the component is generated depends on your website’s framework.

Push to Prismic

When your slice is ready to be used by content writers, add it to a page type and push it to Prismic.

• Add to a page type

  A slice needs to be added to at least one page type before the slice can be used.

  Navigate to the page type you want to update using the sidebar. In the page type’s Slices section, click the Add button and choose Select existing.

  

  In the modal, enable your slice and click Add.

• Push to Prismic

  When your slice and page type are ready for content writers, push it to your Prismic repository.

  Click Review changes in the sidebar. Then, if the changes look correct, click the Push button in the top-right corner.

  

  The Page Builder will now recognize your slice.

Slice variations

Multiple versions of a slice can be modeled as slice variations.

For example, a “Text with Image” slice might have a variation for “Image on Left” and another for “Image on Right.”

Content writers can select a variation in the Page Builder.

Each variation has its own set of fields to account for content differences between variations.

How to add a slice variation

• Open a slice

  In Slice Machine, navigate to the slice you want to modify.

• Add a variation

  In the section next to the slice’s fields, click the Add a variation button.

  

  The variation name determines the label shown to content writers in the Page Builder. Use an easily understood name.

  The variation ID determines the ID used to reference the variation in the Document API. Use a short, camel-cased name.

  The duplicate from dropdown determines which existing variation to use as a starting point for the new variation.

• Add a screenshot

  A screenshot will help content writers select the correct variation.

  Take a screenshot of your slice’s design. Then click the ”…” button and select Update screenshot.

  

• Update the slice component

  Update the slice’s UI component to recognize the slice variation. Use the slice’s variation property to determine which variation was selected.

  if (slice.variation === "withButton") {
    // Display the "With Button" variation.
  } else {
    // Display the default variation.
  }

• Push to Prismic

  When your variation is ready for content writers, push it to your Prismic repository.

  Click Review changes in the sidebar. Then, if the changes look correct, click the Push button in the top-right corner.

  

  The Page Builder will now recognize your variation.

Slice libraries

Developers can use slice libraries to organize a website’s code. A slice library is a directory containing slices and their files.

For example, a developer may group slices for marketing pages into a src/slices/marketing directory and slices for blog posts into a src/slices/blog directory. Each directory is a slice library.

Slice library components

Slice Machine generates an index.ts file for each slice library exporting all of the library’s components. The export is useful for the <SliceZone> component.

See Display slices to learn more.

How to add a slice library

• Open Slice Machine configuration

  Slice libraries are registered in Slice Machine’s configuration file: slicemachine.config.json.

  Open slicemachine.config.json in your text editor.

• Add a slice library

  Slice libraries are listed in the libraries property.

  Add a directory for the new slice library.

  slicemachine.config.json

  Copy

  {
    "repositoryName": "example-prismic-repo",
    "adapter": "@slicemachine/adapter-next",
    "libraries": [
      "./src/slices/marketing",
      "./src/slices/blog"
    ],
    "localSliceSimulatorURL": "http://localhost:3000/slice-simulator"
  }

• Restart the Slice Machine server

  The new slice library will be available after restarting the Slice Machine server.

  If Slice Machine is running, press Control + C in the terminal to stop it. Then start Slice Machine again.

  npx start-slicemachine --open

  The library will now be an option when creating a new slice.

Display slices

Prismic provides components to display a page’s slices for Next.js, Nuxt, and SvelteKit.

<SliceZone
  slices={page.data.slices}
  components={{
    text: TextSlice,
    call_to_action: CallToActionSlice,
  }}
/>

Slice components

Each slice has a corresponding React, Vue, or Svelte component, depending on your website’s framework. A slice’s component is displayed whenever the slice is used in a page.

Slice Machine exports all of a slice library’s components in the library’s index.ts file. The export can be passed directly to <SliceZone>’s components prop.

import { components } from "@/slices";

<SliceZone slices={page.data.slices} components={components} />;

API Response

Here is what a slice looks like from the Document API:

{
  "id": "quote$e568fae3-e996-43c2-af06-dbf42b215cc2",
  "slice_type": "quote",
  "variation": "default",
  "version": "initial",
  "primary": {
    "quote": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
  },
  "items": []
}

The slice’s primary content is determined by the slice’s fields.

A page’s slices are returned as an array:

{
  "id": "YCiUyRUAACQAxfZK",
  "uid": "my-first-post",
  "url": "/blog/my-first-post",
  "type": "blog_post",
  "href": "https://example-prismic-repo.cdn.prismic.io/api/v2/...",
  "tags": ["Tag 1", "Tag 2"],
  "first_publication_date": "2021-02-14T03:22:26+0000",
  "last_publication_date": "2022-07-09T00:36:18+0000",
  "slugs": ["my-first-post"],
  "linked_documents": [],
  "lang": "en-us",
  "alternate_languages": [],
  "data": {
    "title": "My first post",
    "slices": [
      {
        "id": "quote$e568fae3-e996-43c2-af06-dbf42b215cc2"
        // ...
      },
      {
        "id": "text$afba88d2-3ce4-46b5-b42b-b89e8dcd6dc5"
        // ...
      }
    ]
  }
}