Build components with the Svelte SDK

Developer preview

This feature is in developer preview. Use with caution as it may change unexpectedly. For more information, contact us.

Uniform components in Svelte receive flattened props: parameter values are extracted from their ComponentParameter wrappers and spread directly onto the component via Svelte 5's $props(). For example, if a Uniform component has a title parameter of type text, your Svelte component receives a title prop with the string value directly.

Every component also receives a component prop containing the full ComponentInstance, which provides access to raw parameter data, component metadata, variant info, and slots.

Every component rendered via the componentMap receives these props:

PropTypeDescription
componentComponentInstanceThe full component instance with raw parameters, slots, variant, and metadata
[parameterName]flattened valueEach parameter's .value is spread as a top-level prop

Use the ComponentProps<T> type to define your component's props:

<!-- src/lib/components/Hero.svelte --> <script lang="ts"> import { UniformText, UniformRichText } from '@uniformdev/canvas-svelte'; import type { ComponentProps } from '@uniformdev/canvas-svelte'; interface Props extends ComponentProps<{ title?: string; description?: string; }> {} let { title, description, component }: Props = $props(); </script> <section class="hero"> <UniformText parameterId="title" as="h1" placeholder="Enter hero title" /> <UniformRichText parameterId="description" as="div" placeholder="Enter description" /> </section>

Access variant information via the component prop to conditionally style components:

<!-- src/lib/components/Card.svelte --> <script lang="ts"> import { UniformText } from '@uniformdev/canvas-svelte'; import type { ComponentProps } from '@uniformdev/canvas-svelte'; interface Props extends ComponentProps<{ title?: string; description?: string; link?: string; }> {} let { title, description, link, component }: Props = $props(); const isFeatured = $derived(component.variant === 'featured'); </script> <article class="card" class:featured={isFeatured}> <h3> <UniformText parameterId="title" as="span" /> {#if isFeatured} <span class="badge">Featured</span> {/if} </h3> {#if description} <p><UniformText parameterId="description" as="span" /></p> {/if} {#if link} <a href={link}>Learn more &rarr;</a> {/if} </article>

Register variants in the component map using the type__variant format:

export const componentMap: ComponentMap = { card: Card, card__featured: Card, // Same component, different styling via variant check };

UniformText renders text parameters with built-in support for inline editing in the Uniform visual editor:

<UniformText parameterId="title" as="h1" placeholder="Enter title" />
PropTypeDefaultDescription
parameterIdstringRequired. The ID of the parameter to render
asstring'span'The HTML element to render
placeholderstring | ((props: { id: string }) => string)undefinedPlaceholder text shown in the Canvas editor when empty
isMultilinebooleanfalseWhen true, adds white-space: pre-wrap for line break support

Pass render to change the string before it is written.

<UniformText parameterId="title" as="h1" render={(value) => value?.toUpperCase()} />

UniformRichText renders rich text parameters with full formatting support:

<UniformRichText parameterId="description" as="div" placeholder="Enter description" />
PropTypeDefaultDescription
parameterIdstringRequired. The ID of the rich text parameter
asstring | null'div'Wrapper element. null renders the rich text without a wrapper
placeholderstring | ((props: { id: string }) => string)undefinedPlaceholder text when empty
resolveRichTextRendererRenderRichTextComponentResolverundefinedCustom function that replaces the default components for rich text nodes

Override how specific rich text node types are rendered:

<script lang="ts"> import { UniformRichText } from '@uniformdev/canvas-svelte'; import type { RenderRichTextComponentResolver } from '@uniformdev/canvas-svelte'; import CustomHeading from './CustomHeading.svelte'; const resolveRichTextRenderer: RenderRichTextComponentResolver = (node) => { if (node.type === 'heading') { return CustomHeading; } return null; // Use default renderer }; </script> <UniformRichText parameterId="body" as="div" {resolveRichTextRenderer} />

Use flattenValues from @uniformdev/canvas to work with asset parameters:

<script lang="ts"> import type { ComponentProps } from '@uniformdev/canvas-svelte'; import { flattenValues } from '@uniformdev/canvas'; interface Props extends ComponentProps<{}> {} let { component }: Props = $props(); const hero = flattenValues(component.parameters?.featuredImage, { toSingle: true, }); const images = flattenValues(component.parameters?.gallery); </script> {#if hero} <img src={hero.url} width={hero.width} height={hero.height} alt={hero.fields?.alt?.value ?? ''} /> {/if} {#each images ?? [] as img} <img src={img?.url} width={img?.width} height={img?.height} alt="" /> {/each}

warning

Always use flattenValues from @uniformdev/canvas for asset parameters. Do not create custom utility functions for extracting asset data.