# Build components with the Svelte SDK

> Write Svelte components that receive Uniform parameters as props and render text, rich text, variants, and assets.

Source: https://docs.uniform.app/docs/sdk/svelte/building-components

> **Developer preview:**
>
> This feature is in developer preview and may change unexpectedly. For more information, contact support@uniform.dev.

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.

## Component props

Every component rendered via the `componentMap` receives these props:

| Prop | Type | Description |
| --- | --- | --- |
| `component` | `ComponentInstance` | The full component instance with raw parameters, slots, variant, and metadata |
| `[parameterName]` | flattened value | Each parameter's `.value` is spread as a top-level prop |

## Basic component with parameters

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

```svelte
<!-- 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>
```

## Component with variants

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

```svelte
<!-- 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:

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

## UniformText

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

```svelte
<UniformText
  parameterId="title"
  as="h1"
  placeholder="Enter title"
/>
```

### UniformText props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `parameterId` | `string` |  | **Required.** The ID of the parameter to render |
| `as` | `string` | `'span'` | The HTML element to render |
| `placeholder` | `string \| ((props: { id: string }) => string)` | `undefined` | Placeholder text shown in the Canvas editor when empty |
| `isMultiline` | `boolean` | `false` | When `true`, adds `white-space: pre-wrap` for line break support |

### Custom value rendering

Pass `render` to change the string before it is written.

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

## UniformRichText

`UniformRichText` renders rich text parameters with full formatting support:

```svelte
<UniformRichText
  parameterId="description"
  as="div"
  placeholder="Enter description"
/>
```

### UniformRichText props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `parameterId` | `string` |  | **Required.** The ID of the rich text parameter |
| `as` | `string \| null` | `'div'` | Wrapper element. `null` renders the rich text without a wrapper |
| `placeholder` | `string \| ((props: { id: string }) => string)` | `undefined` | Placeholder text when empty |
| `resolveRichTextRenderer` | `RenderRichTextComponentResolver` | `undefined` | Custom function that replaces the default components for rich text nodes |

### Custom rich text node rendering

Override how specific rich text node types are rendered:

```svelte
<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}
/>
```

## Asset parameters

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

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