Svelte Switch Component Development

Expert guidance for developing, showcasing, and documenting Svelte 5 switch components using the @keenmate/svelte-switch library with @keenmate/svelte-docs for documentation structure.

When to Use This Skill

Use this skill when:

Core Competencies

Svelte 5 Reactive Patterns

Always use modern Svelte 5 runes for state management:

```svelte

<script>

// State management

let checked = $state(false);

let selectedIndex = $state(0);

// Derived values

let label = $derived(checked ? 'On' : 'Off');

// Two-way binding

<Switch bind:checked />

<MultiSwitch bind:selectedIndex />

</script>

```

Template Snippet Safety

**CRITICAL**: Always use null safety in template snippets to prevent undefined property errors.

```svelte

<!-- ❌ WRONG - Will cause errors with objects -->

{#snippet labelTemplate(item, index)}

{item.name}

{/snippet}

<!-- ✅ CORRECT - Safe with null checking -->

{#snippet labelTemplate(item, index)}

{item?.name || `Option ${index + 1}`}

{/snippet}

```

Label Positioning System (v1.4.0+)

The label system has two rendering modes:

**Option 1: Block Mode (Recommended for new projects)**

```svelte

<MultiSwitch

items={options}

shouldDisplayLabels={true}

labelRenderMode="block"

labelPosition="bottom" />

```

**Option 2: Absolute Mode (Legacy, requires manual spacing)**

```svelte

<div class="py-5"> <!-- Top/bottom: 3rem top, 2.5rem bottom -->

<MultiSwitch

items={options}

shouldDisplayLabels={true}

labelRenderMode="absolute"

labelPosition="top" />

</div>

```

Spacing requirements for absolute mode:

Object Display in Labels

Use these properties in priority order to display object content properly:

1. **labelMember** - Extract specific property:

```svelte

<MultiSwitch items={products} labelMember="name" shouldDisplayLabels={true} />

```

2. **labelCallback** - Custom formatting function:

```svelte

<MultiSwitch

items={plans}

labelCallback={(item, index) => `${item.tier} - $${item.price}/mo`}

shouldDisplayLabels={true} />

```

3. **labelTemplate** - Full custom rendering:

```svelte

{#snippet labelTemplate(item, index)}

<strong>{item?.name}</strong>

<small>{item?.description || ''}</small>

{/snippet}

<MultiSwitch items={options} {labelTemplate} shouldDisplayLabels={true} />

```

Custom Template Content Sizing

When using custom templates (thumbTemplate, children), follow these constraints:

```svelte

{#snippet thumbTemplate(checked)}

<div class="d-flex align-items-center justify-content-center h-100 w-100">

<i class="bi bi-check fs-6"></i> <!-- Appropriate size for space -->

</div>

{/snippet}

```

**Rules**:

Documentation Site Structure

Using @keenmate/svelte-docs

Structure your showcase with these components:

```svelte

<script>

import { DocLayout, ShowcaseSection, CodeBlock, FeatureCard } from '@keenmate/svelte-docs';

</script>

<DocLayout title="Component Name">

<ShowcaseSection

title="Basic Usage"

demoColumnHeight="300px"> <!-- Use when content exceeds default -->

{#snippet demo()}

<!-- Live interactive example -->

{/snippet}

{#snippet code()}

<CodeBlock language="svelte" code={`...`} />

{/snippet}

{#snippet description()}

<p>Clear explanation of the example</p>

{/snippet}

</ShowcaseSection>

</DocLayout>

```

Demo Container Overrides

Override restrictive `.demo-container` sizing from @keenmate/svelte-docs:

```scss

// app.scss

.showcase-section .demo-container {

max-width: none !important;

max-height: none !important;

overflow: visible !important;

}

```

Documentation Best Practices

1. **Progressive Complexity**: Start simple, build to advanced

- Overview and basic usage

- Simple examples with primitives

- Object handling with labelMember/labelCallback

- Custom templates and styling

- Advanced patterns

2. **API Documentation**:

- Comprehensive prop tables with types

- Version badges (color-coded: blue=1.0.0+, green=1.3.0+, yellow=1.4.0+)

- SCSS variables and CSS custom properties

- Code examples that are copy-pasteable

3. **Interactive Demos**:

- Always provide live examples

- Show state changes (only when not redundant with labels)

- Three-column layout: Demo | Code | Description

- Include edge cases (empty arrays, null values)

Docker Deployment Pattern

Multi-stage Dockerfile

```dockerfile

FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./

RUN npm ci

COPY . .

RUN npm run build

FROM nginx:alpine

COPY --from=builder /app/build /usr/share/nginx/html

COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

```

Nginx Configuration

```nginx

server {

listen 80;

root /usr/share/nginx/html;

index index.html;

# SPA routing

location / {

try_files $uri $uri/ /index.html;

}

# Caching

location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {

expires 1y;

add_header Cache-Control "public, immutable";

}

# Security headers

add_header X-Frame-Options "SAMEORIGIN" always;

add_header X-Content-Type-Options "nosniff" always;

add_header X-XSS-Protection "1; mode=block" always;

# CSP for analytics (adjust domains as needed)

add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' plausible.io; connect-src 'self' plausible.io;" always;

# Compression

gzip on;

gzip_types text/plain text/css application/json application/javascript text/xml application/xml;

}

```

Package Management

```bash

Local development with linked packages

npm link @keenmate/svelte-switch

npm link @keenmate/svelte-docs

Unlink when done

npm unlink @keenmate/svelte-switch

npm unlink @keenmate/svelte-docs

Install specific version for production

npm install @keenmate/[email protected]

Docker commands

docker build -t svelte-switch-showcase .

docker run -p 80:80 svelte-switch-showcase

```

Error Prevention Checklist

Before implementing:

SvelteKit Configuration

```javascript

// svelte.config.js

import adapter from '@sveltejs/adapter-static';

export default {

kit: {

adapter: adapter({

pages: 'build',

assets: 'build',

fallback: 'index.html'

})

}

};

```

Implementation Workflow

1. **Setup**: Install dependencies, configure SvelteKit with static adapter

2. **Basic Components**: Implement simple switch examples with primitives

3. **Object Handling**: Add examples using labelMember and labelCallback

4. **Custom Templates**: Create advanced examples with thumbTemplate and labelTemplate

5. **Styling Demos**: Show SCSS customization and CSS custom properties

6. **Documentation**: Build comprehensive API reference with version badges

7. **Testing**: Validate all edge cases and null safety

8. **Deployment**: Build Docker image with nginx, configure CSP headers

Common Pitfalls to Avoid

1. **Forgetting null safety in templates** - Always use `?.` operator

2. **Wrong spacing for absolute labels** - Use block mode or follow spacing guide

3. **Oversized custom content** - Keep template content compact

4. **Missing object handling** - Use labelMember/labelCallback for objects

5. **Restrictive demo containers** - Override svelte-docs sizing constraints

6. **Redundant state displays** - Remove when labels already show state

7. **Excessive vertical spacing** - Avoid `py-4`, `py-5` unless needed for hierarchy

Version Compatibility

Success Criteria

A successful implementation includes: