Styling

SvSeeds components provide a flexible styling system. This document explains the two primary styling methods and their implementation details.

Overview

String-based Styling

Used when a string is specified for the styling prop, or when no value is provided. The specified class name is automatically applied to each part of the component. When no value is provided, the default component name is used.

Object-based Styling

Used when an object of a specific type is specified for the styling prop. This allows you to specify classes individually for each part of the component. Use this approach when working with TailwindCSS.

String-based Styling

In String-based Styling, the specified class name is applied in combination with each component part and variant.

Example

<script>
  import { Button } from "svseeds";
  const styling = "my-button";
</script>

<Button {styling}>Hello</Button>

<button class="my-button whole neutral">
  <span class="my-button main neutral">
    Hello
  </span>
</button>

<script>
  import { Toggle } from "svseeds";
  const styling = "my-toggle";
</script>

<Toggle {styling}>Hello</Toggle>

<!-- off state -->
<button class="my-toggle main neutral">Hello</button>
<!-- on state -->
<button class="my-toggle main active">Hello</button>

Object-based Styling

In Object-based Styling, you can specify classes individually for each part of the component. For detailed object specifications, see Object for Styling.

Example

<script>
  import { Button } from "svseeds";
  const styling = {
    whole: "m-1 p-1",
    main: "text-md"
  };
</script>

<Button {styling}>Hello</Button>

<button class="m-1 p-1">
  <span class="text-md">
    Hello
  </span>
</button>

<script>
  import { Toggle } from "svseeds";
  const styling = {
    main: {
      base: "text-md",
      neutral: "bg-gray-400",
      active: "bg-blue-400",
    }
  };
</script>

<Toggle {styling}>Hello</Toggle>

<!-- off state -->
<button class="text-md bg-gray-400">Hello</button>
<!-- on state -->
<button class="text-md bg-blue-400">Hello</button>

Part Name System

To ensure styling flexibility, all elements within components are assigned part names.

Standard Part Names

The following part names are defined by default:

• whole - Overall component wrapper
• top - Top region
• middle - Middle region
• bottom - Bottom region
• left - Left area
• main - Main content area
• right - Right area
• label - Label part
• aux - Auxiliary part
• extra - Additional part

Since part names are defined as string type, custom components can also define custom part names. For the specific part names used by each component, refer to the individual component documentation.

Variant System

Component styling adapts based on its current appearance variant.

Standard Variants

The following variant names are defined by default:

• neutral - Default variant
• active - Active variant (such as selected state)
• inactive - Inactive variant (also used for invalid/error states)

Since variants are defined as string type, custom variants can also be used.

Variant Behavior

Components fall into two categories: those that automatically manage their variant based on user interaction, and those that maintain a fixed variant. For detailed variant behavior of each component, refer to the individual component documentation.

Auto-Managing Components

Components like Toggle and TextField automatically update their variant in response to user interactions. For these components, the variant prop serves as an override for the default neutral variant.

Non-Auto-Managing Components

For these components, the variant prop directly sets the component’s variant without any automatic changes.

Theme-based Style Switching

Use CSS prefers-color-scheme to configure theme switching. For theme toggle functionality, refer to the feature details of the DarkToggle component.

Object for Styling

Object Type

The object used in object-based styling is defined as the SVSClass type.

<script>
  import type { SVSClass } from "svseeds";
  const styling: SVSClass = {
    whole: "whole-base",
    main: {
      base: "main-base",
      neutral: "main-neutral",
      active: "main-active",
    }
  };
</script>

Advanced Class Value Specification

Property values can use clsx library-compatible values that are valid for Svelte’s class attribute specification, as well as strings.

const styling = {
  whole: ["whole-class", "class1", "class2"],
  main: {
    base: "main-class",
    neutral: { foo, bar: !foo },
  }
};

Fallback Variant Style

If the current status is not found in the object, the style defined for neutral will be used as a fallback.

<script>
  import { Toggle } from "svseeds";
  const styling = {
    main: {
      base: "text-md",
      neutral: "bg-gray-400",
    }
  };
</script>

<Toggle {styling}>Hello</Toggle>

Generated HTML (class attribute excerpt):

<!-- off state -->
<button class="text-md bg-gray-400">Hello</button>
<!-- on state -->
<button class="text-md bg-gray-400">Hello</button>

Shorthand Notation

You can omit the variant and specify class attribute values directly for part names:

const styling = {
  whole: "whole-class",
  main: "main-class"
};

This is interpreted as:

const styling = {
  whole: {
    base: "whole-class"
  },
  main: {
    base: "main-class"
  }
};

Important Note

When using shorthand notation with objects, the objects must be wrapped in an array:

// NG: Will not be interpreted correctly
const styling = {
  whole: { foo, bar: !foo },
};

// OK: Correct specification
const styling = {
  whole: [{ foo, bar: !foo }],
};

The latter is interpreted as:

const styling = {
  whole: {
    base: [{ foo, bar: !foo }]
  },
};

This array wrapping enables both object specification for class attributes and variant omission to coexist.