Customization

SvSeeds components offer flexible customization options, ranging from simple prop-based modifications to complete component overhauls.

Using Props

Basic Props Configuration

Each component comes with dedicated type definitions, allowing you to leverage TypeScript's type safety for customization.

<script lang="ts">
  import { Button, type ButtonProps } from "svseeds";

  const props: ButtonProps = {
    type: "button",
    styling: "my-button",
  };
</script>

<Button {...props}>Hello</Button>

Customizing Component Parts

Components that support specific parts (such as left, right, bottom, etc.) through props can be customized by specifying Snippet or string types for those parts. Only the specified parts will be rendered, with unnecessary elements automatically excluded.

Example of adding an icon to the left side:

<script>
  import { Button } from "svseeds";
</script>

<Button>
  hello
  {#snippet left()}
    ⭐
  {/snippet}
</Button>

Generated HTML:

<button class="svs-button whole neutral" type="button">
  <span class="svs-button left neutral">⭐</span>
  <span class="svs-button main neutral">hello</span>
</button>

Example of adding an icon to the right side:

<script>
  import { Button } from "svseeds";
</script>

<Button {right}>hello</Button>

{#snippet right()}
  ⭐
{/snippet}

Generated HTML:

<button class="svs-button whole neutral" type="button">
  <span class="svs-button main neutral">hello</span>
  <span class="svs-button right neutral">⭐</span>
</button>

Attribute Customization

Base components accept standard HTML attributes as top-level props and forward unmatched attributes to their main element. Attributes that conflict with component-owned props or compromise component integrity may be omitted from the component type. Some wrapper or Field components expose narrower nested configuration for inner elements; check each component's documentation for those component-specific props.

<script lang="ts">
  import { Button } from "svseeds";
</script>

<Button name="mybutton" data-testid="custom-button">Hello</Button>

Advanced Usage

Direct Element Manipulation (Element Binding)

Components with an element prop allow direct manipulation of the main element using bind:element. Check each component's documentation to see which element the element prop binds to.

<script lang="ts">
  import { Button } from "svseeds";

  let element: HTMLButtonElement | undefined = $state();
  $effect(() => element?.focus());
</script>

<Button bind:element>Hello</Button>

Applying Attachments

Components with an attach prop allow you to apply a Svelte Attachment to the main element. Check each component's documentation to see which element the attachment is applied to.

<script lang="ts">
  import type { Attachment } from "svelte/attachments";
  import { Button } from "svseeds";

  const focus: Attachment<HTMLButtonElement> = (node) => {
    node.focus();

    return () => console.log("cleanup");
  };
</script>

<Button attach={focus}>hello</Button>

Customizing Dependent Components

Some wrapper components render default child components for data-driven usage. They customize those generated children through a typed, namespaced configuration prop whose value is the child props minus parent-owned props.

<script lang="ts">
  import { Accordion, type AccordionProps } from "svseeds";

  const disclosure: AccordionProps["disclosure"] = {
    styling: "my-disclosure",
  };
  const items = [{ value: "1", label: "First", panel }];
</script>

<Accordion {items} {disclosure} />

{#snippet panel(_value: string)}
  content
{/snippet}

Direct Integration with CLI Tool

When you need deep customization that cannot be controlled through props, you can use the CLI tool to add components directly to your project. For details about the CLI tool, see GitHub.

Using the CLI Tool

npx svseeds-cli

pnpm dlx svseeds-cli

yarn dlx svseeds-cli

File Structure

By default, components are copied to the following location:

project-root
└─ src
    └─ lib
        └─ _svseeds
            ├─ _Badge.svelte      # Independent component
            ├─ core.ts            # Shared functions & utilities
            └─ TagsInput.svelte   # Component with dependencies

File naming conventions:

• core.ts: Shared functions and utilities for all components
• _ prefix: Independent components that don't depend on other SvSeeds components
• Regular files: Components that depend on other SvSeeds components (dependencies are automatically added)

Setting Preset Styles

You can set the default style used when no styling prop is specified by modifying the generated _<NAME>_PRESET constant within the component. The value can be either a string or an SVSClass object.

<script module lang="ts">
  import type { SVSClass } from "svseeds";

  export const _BUTTON_PRESET: SVSClass = "my-custom-default-style";
</script>