@storyblok/svelte

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

Practical resources

• Svelte Guide

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

• Space Blueprint: Svelte Opens in new tab

  See the blank space blueprint for Svelte to kickstart a new project.

Requirements

• Svelte 5 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 from a Storyblok space.

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,
	},
});

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.

<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.

/** @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:

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

	export let data;
</script>

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

API

storyblokInit

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

storyblokInit(OPTIONS)

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

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

apiPlugin

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

import { storyblokInit, apiPlugin } from '@storyblok/svelte';

storyblokInit({
	use: [apiPlugin],
});

For more information, see the @storyblok/js package reference.

useStoryblokApi

useStoryblokApi() returns the client instantiated in the application.

useStoryblok(URL, API_OPTIONS, BRIDGE_OPTIONS);

For the API_OPTIONS, see the storyblok-js-client package 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 StoryblokBridge reference.

StoryblokComponent

<StoryblokComponent blok={blok} />

StoryblokComponent is a Svelte component that dynamically renders blocks from Storyblok.

StoryblokComponent 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.

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 package 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 package reference for further details.

Further resources