Components

Dev Server

To run all packages/playgrounds/sites in watch mode, use the following command in the monorepo root:

pnpm dev

If you wish to focus on a specific framework you may run the framework-specific dev command:

pnpm dev:{framework}

This will limit the monorepo to only running the framework package (and its dependencies) and the corresponding playground for the specified framework and thus reduce resource usage and console bloat.

Server Ports

The following represents the default localhost address and port for each project. This will be displayed in the terminal when starting each dev server.

• Documentation Site: http://localhost:4321/
• Svelte Playground: http://localhost:5173/
• React Playground: http://localhost:3000/

You may run the sites and playgrounds in parallel at the same time. If a server shares a port, this will increment by one for the next server (ex: 5174, 5175, etc). Keep your eye on the terminal to retrieve the specific local address for each.

Zag.js

Skeleton components are built using a foundation of Zag.js. This provides a suite of headless component primitives that handle logic and state, while providing a universal set of features per all supported frameworks. The Skeleton design system is then implemented as a layer on top of this.

When introducing a new Skeleton component, please refer to the documentation for each respective framework. For example:

• Avatar (React): https://zagjs.com/components/react/avatar
• Avatar (Svelte): https://zagjs.com/components/svelte/avatar

Continue reading below to learn how implement the Zag primitives as components using Skeleton-specific conventions.

Adding Components

Anatomy

When creating a component, start by breaking it down into its core parts. If the component utilizes a Zag primitive, you may copy the source directly from Zag’s Usage section. For custom in-house components, you may use Skeleton’s common terminology and discuss the potential anatomy with the Skeleton team.

For example, the Zag Avatar component utilizes the following DOM structure:

<div>
  <img />
  <span>...</span>
</div>

As such, we’ll implement one component part respective of each element:

• <Avatar> - the root element
• <Avatar.Image> - the child image
• <Avatar.Fallback> - the fallback span

Directory and File Names

Components are housed in the following location per framework:

Skeleton uses a consistent naming convention per component:

avatar/
├── anatomy/
│   ├── avatar-fallback.{tsx|svelte}
│   ├── avatar-image.{tsx|svelte}
│   ├── avatar-root-context.{tsx|svelte}
│   └── avatar-root.{tsx|svelte}
├── modules/
│   ├── avatar-anatomy.ts
│   └── avatar-root-context.ts
└── index.ts

Anatomy Folder

The anatomy folder contains each component part inside a seperate file.

Component Part File

Every component part should export their component as a default export and their prop types as named exports.

React

export interface AvatarRootProps {
  // ...
}

export default function (props: AvatarRootProps) {
  // ...
}

Svelte

<script lang="ts" module>
  export interface AvatarRootProps {
    // ...
  }
</script>

<script lang="ts">
  const props: AvatarRootProps = $props();

  // ...
</script>

<!-- ... --->

Modules Folder

Anatomy File

The {component}-anatomy.ts file contains the exported anatomy, which enables the friendly dot notation syntax when consumed.

import AvatarRoot from '../anatomy/avatar-root.js';
import AvatarImage from '../anatomy/avatar-image.js';
import AvatarFallback from '../anatomy/avatar-fallback.js';

export const Avatar = Object.assign(
  AvatarRoot, // <Avatar>
  {
    Image: AvatarImage, // <Avatar.Image>
    Fallback: AvatarFallback // <Avatar.Fallback>
  }
);

Context Part File

The {component}-{part}-context.ts file contains the exported context for each part’s context. This pattern enables strong typing.

import { createContext } from 'react';

export interface AvatarContextType {
  // ...
}

export const AvatarContext = createContext<AvatarContextType>(null!);

NOTE: The interface is suffixed Type to avoid conflicting with the context reference itself.

Index File

The index prepares all above files for export.

export { Avatar } from './modules/avatar-anatomy.js';
export type { AvatarRootProps } from './anatomy/avatar-root.js';
export type { AvatarRootContextProps } from './anatomy/avatar-root-context.js';
export type { AvatarImageProps } from './anatomy/avatar-image.js';
export type { AvatarFallbackProps } from './anatomy/avatar-fallback.js';
export type { AvatarRootContextType as AvatarRootContext } from './modules/avatar-root-context.js';

Component Exports

Finally, make sure to implement the expoorts for each respective component’s framework package. This is handled in /packages/skeleton-{framework}/src/index.ts.

export * from './components/accordion/index.js';
export * from './components/avatar/index.js';
// ...

Using Zag Primitives

Source Code

Locate the respective framework component source code on the Zag website. Here’s Avatars for example:

In most cases, Zag provides all source code in a single file. Take care when splitting this into multiple component parts. We recommend starting with the root component - including the primitive imports, and defining the machine and api. Then utilize Context API and child components for each additional sub-component.

Context API

In some cases you may need to pass data from parent down to child components. For this, we can utilize each framework’s Context API:

Note that Skeleton implements a set convention for Context API to enable strong typing.

Common Conventions

While each component will present a unique set of challenges, we recommend you reference other existing components to understand how they were implemented. But there are a few common conventions we’ll detail below.

• Try to stick as close to the Zag implementation DOM structure and naming as possible; don’t get creative.
• Avoid hardcoded english text or icons. Consider pass-throughs using props, snippets, or sub-components.
• React-Only: Replace the hardcoded id with useId()
• Svelte-Only: Replace the hardcoded id with $props.id()

NOTE: if you’re a contributor reading this and you feel there are more conventions to share. Please consider bringing this up with the Skeleton team. We might ask you to append these as you work on your contributions. The more knowledge we share, the more everyone benefits!

Styling Components

Styles are common and shared between all framework iterations of the same component. These reside in the skeleton-common package and are named to match their respective component.

packages/
└── skeleton-common/
  └── src/
    └── classes/
      ├── accordion.ts
      ├── avatar.ts
      └── ...

Here’s an example of the Avatar styles found in avatar.ts:

import { defineSkeletonClasses } from '../internal/define-skeleton-classes.js' with { type: 'macro' };

export const classesAvatar = defineSkeletonClasses({
  root: 'isolate bg-surface-400-600 size-16 rounded-full overflow-hidden',
  image: 'w-full object-cover',
  fallback: 'size-full flex justify-center items-center'
});

• We’ll cover the import { type: 'macro'} in the next section.
• Use the naming convention of classes{Component}
• Create a key for each component part.
• Set the value to each component’s default class list.

Style Prefix

It’s worth noting that during build time, Skeleton will automatically prefix each class in the class list with skb: (short for “Skeleton Base”). By applying with { type: 'macro' } to the import, the import will run defineSkeletonClasses specifically at build time. This variant prefix will assign each class to the Tailwind @base layer, ensuring user-provided classes take precedence over our internally defined classes. This is accomplished using the following Tailwind custom variant.

/* Found in `/packages/skeleton/src/variants/base.css` */

@custom-variant skb {
  @layer base {
    @slot;
  }
}

If you need to prevent a class from being prefixed at build time, apply a variant of not-skb: to that class.

Importing Class Lists

For Zag primitives, you can import and implement each class list Using Zag’s mergeProps utility for attributes.

import { mergeProps } from '@zag-js/react';
import { classesAvatar } from '@skeletonlabs/skeleton-common';

export default function (props: AvatarRootProps) {
  // ...

  const attributes = mergeProps(
    // api.getRootProps(),
    { className: classesAvatar.root }
    // restAttributes
  );

  // return();
}

The process is similar for custom components without Zag primitives. We still use the Zag mergeProps utility.

import { mergeProps } from '@zag-js/react';
import { classesNavigation } from '@skeletonlabs/skeleton-common';

export default function (props: NavigationRootProps) {
  // ...

  const attributes = mergeProps(
    // api.getRootProps(),
    { className: classesNavigation.root }
    // restAttributes
  );

  // return();
}

Additional Resources

• Component Party - easily compare features between each framework
• React Documentation - the React documentation website.
• Svelte Documentation - the Svelte documentation website.