@storyblok/svelte

@storyblok/svelte is Storyblok’s official development for Svelte applications.

Requirements

• Svelte version 5.0 or later
• Node.js LTS (version 22.x recommended)
• Modern web browser (e.g., Chrome, Firefox, Safari, Edge – latest versions)

Installation

Add the package to a project by running this command in the terminal:

npm install @storyblok/svelte@latest

Usage

Configuration

Import and initialize the SDK using the access token of a Storyblok space.

src/layouts/+layout.js

import { apiPlugin, storyblokInit } from "@storyblok/svelte";
import Page from "./Page.svelte";
import Feature from "./Feature.svelte";

storyblokInit({
  accessToken: "YOUR_ACCESS_TOKEN",
  region: "eu",
  use: [apiPlugin],
  components: {
    page: Page,
    feature: Feature,
  },
});

Tip

Learn how to retrieve an access token in the access tokens concept.

Caution

The region parameter must be specified unless the space was created in the EU. Learn more in the @storyblok/js reference.

Components

Create a Svelte component for each block defined in Storyblok and registered in the configuration (include the page block). Each component will receive a blok prop, containing the content of the block.

src/lib/Feature.svelte

<script>
  import { storyblokEditable } from "@storyblok/svelte";

  export let blok;
</script>

<div use:storyblokEditable="{blok}">
  <h2>{blok.name}</h2>
</div>

Fetching and rendering

In a +page.js file, use the client to fetch a story and render the content using StoryblokComponent.

src/routes/+page.js

/** @type {import('./$types').PageLoad} */
export async function load({ parent }) {
  const { storyblokAPI } = await parent();
  const response = await storyblokAPI.get("cdn/stories/home");
  return {
    story: response.data.story,
  };
}

Then render the content in +page.svelte with StoryblokComponent:

src/routes/+page.svelte

<script>
  import { StoryblokComponent } from "@storyblok/svelte";

  export let data;
</script>

<StoryblokComponent blok="{data.story.content}" />

API

storyblokInit

storyblokInit() creates an instance of the Storyblok API client and loads the Storyblok Bridge.

import { storyblokInit } from "@storyblok/svelte";

storyblokInit(OPTIONS);

All options listed in the @storyblok/js reference are available. The following additional options are available:

Key	Description	Type
components	An object that maps Svelte components to Storyblok blocks. Each component receives a blok prop containing the content of the block.	object

apiPlugin

apiPlugin configures the implementation of the Storyblok API. It is imported from @storyblok/js.

import { storyblokInit, apiPlugin } from "@storyblok/svelte";
storyblokInit({
  use: [apiPlugin],
});

See the @storyblok/js reference for further details.

useStoryblokApi

useStoryblokApi() returns the client instantiated in the application.

useStoryblok(URL, API_OPTIONS, BRIDGE_OPTIONS);

For the API_OPTIONS, see the storyblok-js-client reference.

getStoryblokApi

getStoryblokApi() is an alias of useStoryblokApi().

useStoryblokBridge

useStoryblokBridge() activates the Storyblok Bridge.

import { onMount } from 'svelte'
import { useStoryblokBridge } from '@storyblok/svelte';
onMount(() => {
  useStoryblokBridge(STORY_ID, CALLBACK, BRIDGE_OPTIONS)
}

For the BRIDGE_OPTIONS, see the @storyblok/preview-bridge reference.

StoryblokComponent

StoryblokComponent is a Svelte component that dynamically renders blocks from Storyblok. It accepts a blok prop, which should be a block from the Storyblok API. Any other props passed to StoryblokComponent will be passed directly to the block component.

<StoryblokComponent blok="{blok}" />

Use it to iterate over blocks fields as follows:

<script>
  import { StoryblokComponent } from "@storyblok/svelte";
  export let blok;
</script>
{#each blok.body as blok}
<StoryblokComponent {blok} />
{/each}

storyblokEditable

storyblokEditable() accepts a block from the Storyblok API and returns an object containing the HTML attributes to make elements editable in the Storyblok Visual Editor. See the @storyblok/js reference for further details.

As a Svelte action, storyblokEditable() should be called with Svelte’s use: directive, provided with a blok property:

<script>
  import { storyblokEditable } from "@storyblok/svelte";

  export let blok;
</script>

<div use:storyblokEditable="{blok}">{blok.title}</div>

renderRichText

This function converts a Storyblok rich text field into HTML.

<script>
  import { renderRichText } from "@storyblok/svelte";

  let renderedRichText = $derived(renderRichText(blok.richtext_field));

  export let blok;
</script>

<div>{@html renderedRichText}</div>

See the @storyblok/richtext reference for further details.

Further resources

Repository Playground See the repository playground for additional examples.

Svelte Guide See the Svelte guide for a comprehensive walkthrough on integrating Storyblok with Svelte.

Space Blueprint: Svelte See the core space blueprint for Svelte to kickstart a new project.