@storyblok/svelte
@storyblok/svelte is Storyblok’s official development for Svelte applications.
Practical resources
Section titled “Practical resources”Requirements
Section titled “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
Section titled “Installation”Add the package to a project by running this command in the terminal:
npm install @storyblok/svelte@latest
Configuration
Section titled “Configuration”Import and initialize the SDK using the access token of 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
Section titled “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
Section titled “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}" />
storyblokInit
Section titled “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
Section titled “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
Section titled “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
Section titled “getStoryblokApi”getStoryblokApi()
is an alias of useStoryblokApi()
.
useStoryblokBridge
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “Further resources”Get in touch with the Storyblok community