Atoms
The fundamental building blocks of Svelte Atoms - primitive components that power everything.
What Are Atoms?
Atoms are the most primitive components in the library - simple, focused, and composable.
In chemistry, atoms are the basic units that combine to form molecules. In Svelte Atoms, the same principle applies: atoms are the fundamental components that combine to create more complex UI patterns.
Unlike traditional component libraries that provide fully-featured components, atoms give you the raw building blocks. They handle the hard parts (accessibility, keyboard navigation, state management) while giving you complete control over structure and styling.
Core Concepts
Understanding these concepts will help you get the most out of atoms.
Primitive Components
Atoms are unstyled by default. They provide behavior, accessibility, and state management without imposing design decisions. You add the styling.
Render Props Pattern
Many atoms use render props (snippet slots in Svelte 5) to give you full control over rendering. The atom handles logic, you handle markup.
Composition Over Configuration
Instead of dozens of props for every possible use case, atoms compose together. Build what you need from simple pieces.
Anatomy of an Atom
Let's look at how an atom works with a simple example.
<script lang="ts">
import { HtmlAtom as Atom, defineVariants } from '@svelte-atoms/core';
let { ...restProps } = $props();
// Define component local variants
const variants = defineVariants({
variants: {
variant: {
'primary': {
class: '',
// Primary variant configuration goes here
},
'secondary': {
class: '',
// Secondary variant configuration goes here
}
}
},
compounds: [],
defaults: {
variant: 'primary'
}
});
</script>
<Atom
preset="custom-preset"
as="button"
base={undefined}
{variants}
class="px-4 py-2 rounded bg-blue-500 text-white"
onclick={() => console.log('clicked')}
>
Click me
</Atom>
<!-- Renders as: -->
<button class="px-4 py-2 rounded bg-blue-500 text-white">
Click me
</button>
<!-- plus configuration defined in the preset, so the output may look different -->Key Features
-
Polymorphic: The
asprop lets you render any HTML element -
Type-safe: Full TypeScript support with proper types for the rendered element
-
Flexible: Accepts all standard HTML attributes for the element type
When to Use Atoms
Atoms shine in specific scenarios. Here's when to reach for them.
Building Custom Components
Use atoms as the foundation for your own component library. Atoms provide powerful features that make building custom components easier:
- • Preset configuration for consistent styling across your app
- • Animation lifecycles for smooth transitions and effects
- • Base/as props for polymorphic rendering and flexible composition
Need Full Control
When pre-built components are too opinionated, atoms give you the power to build exactly what you need.
Prototyping Rapidly
Quickly compose interfaces without fighting with pre-built component constraints.
Atoms vs Full Components
Understanding the difference helps you choose the right tool.
Atoms
- + Maximum flexibility
- + Preset configuration system
- + Animation lifecycles built-in
- + Polymorphic (base/as props)
- + Minimal bundle size
- + No styling constraints
- - More setup required
Full Components
- + Ready to use
- + Pre-styled
- + Common patterns built-in
- - Less flexible
- - Larger bundle
- - Fixed styling approach
Getting Started with Atoms
Ready to start building with atoms?