Notion Avatar Svelte

A customizable Notion-style avatar editor built with Svelte 5, featuring a clean, responsive UI and modern state management.

Try it: https://avatar.daniel.sticker.name/

• Undo/Redo Support: Full history tracking with Runed StateHistory
• Intuitive Avatar Editor: Customize faces, hair, accessories, and more
• State Management: Built with Svelte 5 Runes and Runed
• Import/Export: Save and load avatar configurations as JSON
• Mobile-Friendly: Responsive design works on all screen sizes
• Accessible UI: Built with shadcn-svelte components for accessibility

Quick Start with jsrepo

The easiest way to add the Notion Avatar Editor to your Svelte 5 project:

Prerequisites

• Svelte 5 project
• jsrepo CLI
• bun (recommended, this guide uses bun but you can use npm or pnpm if you prefer)

Installation

# Install jsrepo CLI (if not already installed)
bun add -g jsrepo
 
# Initialize shadcn-svelte in your project (if not already done)
bunx shadcn-svelte@next init
 
# Add the avatar editor component
jsrepo add @stickerdaniel/notion-avatar-svelte/ui/avatar-editor

Usage

add to your +layout.svelte:

<!-- src/routes/+layout.svelte -->
<script lang="ts">
	import '../app.css';
	import { avatarContext } from '$lib/components/ui/avatar-editor/avatarContext';
	import { AvatarStoreClass } from '$lib/components/ui/avatar-editor/AvatarStore.svelte';
 
	let { children } = $props();
 
	// Instantiate and set the AvatarStore in the context
	// This makes it available to all child components within this layout.
	avatarContext.set(new AvatarStoreClass());
</script>
 
{@render children()}

and then render the Avatar Editor:

<script lang="ts">
	import AvatarCreator from '$lib/components/ui/avatar-editor/avatar-editor.svelte';
</script>
 
<AvatarCreator />

You can access the avatar context in any component:

<script lang="ts">
	import * as Avatar from '$lib/components/ui/avatar';
	import { avatarContext } from '$lib/components/ui/avatar-editor/avatarContext';
	// Get the shared avatar store
	const avatar = avatarContext.get();
</script>
 
<pre class="text-xs">{JSON.stringify(JSON.parse(avatar.configJSON), null, 2)}</pre>
<Avatar.Root>
	<Avatar.Image src={avatar.svgDataUrl} />
	<Avatar.Fallback>Avatar</Avatar.Fallback>
</Avatar.Root>

Manual Installation

Prerequisites

• Bun
• Git

Clone the Repository

git clone https://github.com/stickerdaniel/notion-avatar-svelte
cd notion-avatar-svelte

Or download and extract the zip file.

Install Dependencies

# Install dependencies
bun install

Lets run the development server

The project includes tasks for common operations. They work for VSCode and all forked editors like Cursor.

1. Press Cmd+Shift+B (macOS) or Ctrl+Shift+B (Windows/Linux) to run the default build task
2. Select "bun dev (run dev server)" from the task list

Or, open the Command Palette (Cmd+Shift+P or Ctrl+Shift+P) and type "Run Task", then select "bun dev (run dev server)".

Command Line

# Start the development server
bun run dev
 
# Or start the server and open in a browser
bun run dev -- --open

The application will be available at http://localhost:5173/.

Architecture Overview

State Management

The application uses a modern state management approach with Svelte 5 Runes and the Runed library:

// Class-based store with Svelte 5 Runes
export class AvatarStoreClass implements IAvatar {
	// Reactive state with $state rune
	configJSON = $state<string>('');
 
	// Undo/Redo History tracking with Runed
	private _history: StateHistory<string>;
}

Key aspects of the state management:

• Single Source of Truth: The configJSON string is the core state that drives everything
• Derived Values: Computed properties using $derived reactively update when dependencies change
• History Management: The StateHistory class from Runed provides undo/redo functionality
• Context API: The store is made available app-wide using Runed's Context system

Customization

Theming

The project uses Tailwind CSS with customizable themes via shadcn-svelte:

1. Visit shadcn-svelte themes to explore and customize the color palette
2. Edit the src/app.css file to apply your custom theme variables

Adding New Avatar Parts

To add new avatar parts:

1. Add SVG files to src/lib/components/ui/avatar-editor/assets/parts/[category]/[category]-[index].svg
2. Add preview images to src/lib/components/ui/avatar-editor/assets/preview/[category]/[index].svg
3. Update the DEFAULT_CATEGORIES array in src/lib/components/ui/avatar-editor/types.ts

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

• Inspired by Mayandev/notion-avatar
• Built with Svelte 5
• UI components from next.shadcn-svelte.com
• State management with Runed

This project is not affiliated with Notion. The avatar style is inspired by Notion's UI.