Skip to content

@storyblok/angular (Version 2.x)

@storyblok/angular is Storyblok’s official SDK for Angular applications.

  • Angular version 19 or later
  • Node.js LTS (version 22.x recommended)
  • Modern web browser (for example, Chrome, Firefox, Safari, Edge—latest versions)

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

Terminal window
npm install @storyblok/angular@latest

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

src/app/app.config.ts
import { ApplicationConfig, provideBrowserGlobalErrorListeners } from "@angular/core";
import { provideRouter, withComponentInputBinding } from "@angular/router";
import { routes } from "./app.routes";
import { provideClientHydration, withEventReplay } from "@angular/platform-browser";
import { provideStoryblok, withLivePreview, withStoryblokComponents, type StoryblokClientConfig } from "@storyblok/angular";
const sbConfig: StoryblokClientConfig = {
accessToken: "YOUR_ACCESS_TOKEN",
region: "eu",
inlineRelations: true,
};
export const appConfig: ApplicationConfig = {
providers: [
provideBrowserGlobalErrorListeners(),
provideRouter(routes, withComponentInputBinding()),
provideClientHydration(withEventReplay()),
provideStoryblok(
sbConfig,
withStoryblokComponents({
page: () => import("./components/page/page.component").then((m) => m.PageComponent),
}),
withLivePreview()
),
],
};

Create an Angular component for each block defined in Storyblok and registered in the configuration. Each component receives a blok prop that contains the content of the block.

src/app/components/feature/feature.component.ts
import { Component, ChangeDetectionStrategy, input } from "@angular/core";
export interface FeatureBlok {
headline?: string;
}
@Component({
selector: "app-feature",
changeDetection: ChangeDetectionStrategy.OnPush,
template: `<h3>{{ blok().headline }}</h3>`,
})
export class FeatureComponent {
readonly blok = input.required<FeatureBlok>();
}

Use <sb-component> to automatically render nested components (provided they are registered globally).

src/app/components/page/page.component.ts
import { Component, ChangeDetectionStrategy, input, computed } from "@angular/core";
import { type SbBlokData, StoryblokComponent } from "@storyblok/angular";
export interface PageBlok {
body?: SbBlokData[];
}
@Component({
selector: "app-page",
standalone: true,
changeDetection: ChangeDetectionStrategy.OnPush,
imports: [StoryblokComponent],
template: `
<div>
<sb-component [sbBlok]="bloks()" />
</div>
`,
})
export class PageComponent {
readonly blok = input.required<PageBlok>();
readonly bloks = computed(() => this.blok().body ?? []);
}

Use the client to fetch a story and render the content using StoryblokComponent.

src/app/routes/home/home.component.ts
import { Component, ChangeDetectionStrategy, inject, signal, computed, OnInit } from "@angular/core";
import { StoryblokComponent, StoryblokService, Story } from "@storyblok/angular";
@Component({
selector: "app-home",
changeDetection: ChangeDetectionStrategy.OnPush,
imports: [StoryblokComponent],
template: `
<div>
<!-- Pass content directly - component handles null internally -->
<sb-component [sbBlok]="storyContent()" />
</div>
`,
})
export class HomeComponent implements OnInit {
private readonly storyblok = inject(StoryblokService);
private client = this.storyblok.getClient();
readonly story = signal<Story | null>(null);
readonly loading = signal(true);
readonly storyContent = computed(() => this.story()?.content);
async ngOnInit(): Promise<void> {
try {
const { data } = await this.client.stories.get("home", {
query: {
version: "draft",
},
});
this.story.set((data?.story as Story) || null);
} catch (error) {
throw error;
} finally {
this.loading.set(false);
}
}
}

Import and initialize the SDK to access and configure all features.

import { provideStoryblok } from "@storyblok/angular";
provideStoryblok(OPTIONS);

provideStoryblok() creates an instance of the Storyblok Content Delivery API (CAPI) client and loads the Storyblok Bridge.

The following options are available:

Key Description Type
config All options listed in the @storyblok/api-client package reference are available in the first parameter. StoryblokClientConfig
withStoryblokComponents An object that maps Angular components to Storyblok blocks. Each component receives a blok input containing the content of the block. object
withLivePreview Enables or disables live preview for the Angular application. BridgeParams | undefined
withStoryblokRichtextComponents An object that maps Angular components to Storyblok rich text mark and nodes. Each component receives a data input containing the content of the richtext. object

Register Angular components as follows. The key represents the technical name of the Storyblok block, the value represents the Angular component. It supports both lazy and eager loading.

import { type StoryblokComponentsMap } from "@storyblok/angular";
import { PageComponent } from "./components/page/page.component";
const storyblokComponents: StoryblokComponentsMap = {
page: PageComponent,
teaser: () => import("./components/teaser/teaser.component").then((m) => m.TeaserComponent),
grid: () => import("./components/grid/grid.component").then((m) => m.GridComponent),
feature: () => import("./components/feature/feature.component").then((m) => m.FeatureComponent),
"featured-articles": () => import("./components/feature-posts/feature-posts.component").then((m) => m.FeaturePostsComponent),
"article-overview": () => import("./components/article-overview/article-overview.component").then((m) => m.ArticleOverviewComponent),
article: () => import("./components/article/article.component").then((m) => m.ArticleComponent),
};
provideStoryblok(withStoryblokComponents(storyblokComponents));

withLivePreview enables and disables live preview for the Angular application. Pass BridgeParams to configure the Storyblok Bridge globally.

withLivePreview({
resolveRelations: ['feature_posts.posts'],
}),

Register custom Angular components for rich text nodes and marks.

The key is the technical name of the Storyblok node or mark, and the value is the Angular component used to render it. Both eager and lazy loaded components are supported, with full type safety for keys and component props.

withStoryblokRichtextComponents({
link: () => import("./components/richtext/link.component").then((m) => m.LinkComponent),
heading: () => import("./components/richtext/heading.component").then((m) => m.HeadingComponent),
});

Learn more about custom rich text components in the <sb-rich-text> section.

StoryblokService is the main entry point to access the underlying Storyblok @storyblok/api-client. It provides a typed, framework-aware wrapper with full access to the official Storyblok API client.

Use getClient() when you need direct access to the Storyblok SDK methods (for example, to fetch stories, datasources, or links).

const client = inject(StoryblokService).getClient();
const { data } = await client.stories.get(path, {
query: {
version: "draft",
resolve_relations: "featured-articles.articles",
},
});

Learn more in the @storyblok/api-client reference.

LivePreviewService enables real-time updates from the Storyblok Visual Editor. It listens for story changes and automatically updates your local state when editing in preview mode.

Call listen() with a callback that receives the updated story. To stop listening automatically when the component is destroyed, pass its DestroyRef as destroyRef instead of cleaning up in ngOnDestroy. The remaining options are the Storyblok Bridge configuration (BridgeParams), merged over the configuration passed to withLivePreview().

export class ExampleComponent implements OnInit {
private readonly livePreview = inject(LivePreviewService);
private readonly destroyRef = inject(DestroyRef);
private readonly story = signal<Story | null>(null);
ngOnInit(): void {
void this.livePreview.listen((updatedStory) => this.story.set(updatedStory), {
destroyRef: this.destroyRef,
resolveRelations: ["featured-articles.articles"],
});
}
}

Without destroyRef, call the cleanup function that listen() resolves to when the subscription is no longer needed:

const cleanup = await this.livePreview.listen((updatedStory) => this.story.set(updatedStory));
// Later, to stop listening:
cleanup();

listen() accepts these options in addition to BridgeParams:

Option Description Type
destroyRef Stops listening when the DestroyRef is destroyed. If it’s already destroyed, nothing is subscribed. DestroyRef | undefined
onChange Called when the story is saved or published, instead of reloading the page. Use it to fetch the data again. The page still reloads unless every active subscription passes onChange. (event) => void | undefined
onError Called if the Storyblok Bridge fails to load. Defaults to logging the error with console.error. (error: unknown) => void | undefined

All listen() calls in an application share a single Storyblok Bridge instance. The SDK combines the resolveRelations values of all active subscriptions. For other options, the SDK uses the first value that an active subscription provides. The callback, onChange, and onError run inside the Angular zone.

This keeps responsibilities clean: StoryblokService handles data fetching, while LivePreviewService manages real-time synchronization.

<sb-component> renders Storyblok blocks dynamically. The sbBlok input accepts either a single Storyblok block or an array of blocks.

<sb-component [sbBlok]="blok.body" />

SbBlokDirective renders a single Storyblok block dynamically inside an Angular template. It accepts a sbBlok input.

<ng-container [sbBlok]="blok" />

<sb-rich-text> renders a rich text field from a Storyblok story.

<sb-rich-text [sbDocument]="blok.richtext_field" />

The component accepts an optional optimizeImage input, which configures image optimization for image nodes.

Learn more about supported rich text nodes, marks, and customization options in the @storyblok/richtext reference.

Register custom components with withStoryblokRichtextComponents when you configure provideStoryblok. The key must match a supported rich text node or mark name.

import type { SbAngularRichTextComponentMap } from "@storyblok/angular";
import { withStoryblokRichtextComponents } from "@storyblok/angular";
import CustomHeading from "./CustomHeading.component";
import CustomLink from "./CustomLink.component";
import CustomTable from "./CustomTable.component";
const components: SbAngularRichTextComponentMap = {
heading: CustomHeading,
link: CustomLink,
table: CustomTable,
};
provideStoryblok(withStoryblokRichtextComponents(components));

Each component receives a required data input with the rich text node or mark data.

Marks receive their attributes through SbAngularRichTextProps<T> and can render their content using <ng-content>.

import { ChangeDetectionStrategy, Component, input } from "@angular/core";
import type { SbAngularRichTextProps } from "@storyblok/angular";
@Component({
selector: "app-link",
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<a [href]="data().attrs?.href">
<ng-content />
</a>
`,
host: {
style: "display: inline-block",
},
})
export class LinkComponent {
readonly data = input.required<SbAngularRichTextProps<"link">>();
}

Nodes receive their child nodes through content. <sb-rich-text> renders these child nodes recursively.

import { ChangeDetectionStrategy, Component, computed, input } from "@angular/core";
import { SbRichTextComponent, type SbAngularRichTextProps } from "@storyblok/angular";
@Component({
selector: "app-heading",
changeDetection: ChangeDetectionStrategy.OnPush,
imports: [SbRichTextComponent],
template: `
@switch (level()) {
@case (1) {
<h1>
<sb-rich-text [sbDocument]="data().content" />
</h1>
}
@default {
<div>
<sb-rich-text [sbDocument]="data().content" />
</div>
}
}
`,
host: {
style: "display: contents",
},
})
export class HeadingComponent {
readonly data = input.required<SbAngularRichTextProps<"heading">>();
readonly level = computed(() => this.data().attrs?.level ?? 1);
}

Example: Custom table component (advanced node)

Section titled “Example: Custom table component (advanced node)”

For advanced use cases, nodes can use the splitTableRows utility to separate table rows into header and body sections.

import { ChangeDetectionStrategy, Component, computed, input } from "@angular/core";
import { SbRichTextComponent, splitTableRows, type SbAngularRichTextProps } from "@storyblok/angular";
@Component({
selector: "app-table",
changeDetection: ChangeDetectionStrategy.OnPush,
imports: [SbRichTextComponent],
template: `
<table>
@if (tableRows().headerRows.length) {
<thead>
<sb-rich-text [sbDocument]="tableRows().headerRows" />
</thead>
}
@if (tableRows().bodyRows.length) {
<tbody>
<sb-rich-text [sbDocument]="tableRows().bodyRows" />
</tbody>
}
</table>
`,
host: {
style: "display: contents",
},
})
export class TableComponent {
readonly data = input.required<SbAngularRichTextProps<"table">>();
readonly tableRows = computed(() => splitTableRows(this.data().content));
}

The Angular SDK also exports the core rich text utilities from @storyblok/richtext. These can be useful when implementing advanced custom components, such as custom image or table rendering.

Available utilities include:

  • renderRichText: The core rich text rendering function.
  • buildStoryblokImage: Generates optimized Storyblok Image Service URLs.
  • splitTableRows: Splits table rows into headerRows and bodyRows.

Was this page helpful?

What went wrong?

This site uses reCAPTCHA and Google's Privacy Policy (opens in a new window).Terms of Service (opens in a new window) apply.