Skip to content

Icons and images ​

Typed Lucide icons that you can use in Kotlin DTOs and Svelte alike, and pictures that are resized and converted at build time.

Gradle Generated files

This page is part of Frontend libraries. Run ./gradlew svelteSync after every change to the libraries { } block.

Quick start ​

kotlin
svelte {
    libraries {
        lucide()
        images()
    }
}
svelte
<script lang="ts">
    import Icon from '#icon';
</script>

<Icon name="ArrowRight" size={20} />
<enhanced:img src="#lib/assets/hero.png" alt="Our team" />

Lucide icons ​

lucide() installs Lucide for Svelte and generates a LucideIcon enum from the installed version, so a misspelled icon is a compile error, in Kotlin and in TypeScript.

In Svelte ​

svelte
<script lang="ts">
    import Icon from '#icon';
</script>

<Icon name="ArrowRight" size={20} />
<Icon name={note.icon} class="text-primary" />
PropWhat it does
nameThe icon, typed as LucideIconName. A typo fails svelteCheck
sizeWidth and height, as a number of pixels or any CSS length
colorThe stroke color. Without it the icon takes the text color
strokeWidthThe width of the lines
classClasses for the <svg>, such as text-primary or inline

Each icon loads on demand, so you only download the ones a page uses.

In Kotlin ​

The enum is generated in the generated package. Use it in your DTOs, and it reaches the frontend as the same type:

kotlin
import io.github.nijasc.ktorsvelte.LucideIcon

@Serializable
data class Note(val title: String, val icon: LucideIcon)

A misspelled icon name from a client gets a 400 from Ktor, like any other invalid enum value.

Icon names ​

An icon's enum name is its Lucide name in PascalCase:

Lucide nameEnum name
arrow-rightArrowRight
square-checkSquareCheck
layout-dashboardLayoutDashboard
a-arrow-downAArrowDown

Names starting with a digit get an Icon prefix.

Only the icons you use ​

Only the icons your app uses are built into the frontend. svelteSync finds them in your Kotlin code (LucideIcon.Flame) and in your frontend (name="ArrowRight", Icon.Tags, or a string such as 'Search'), and writes just those into src/lib/ktor-svelte/icons.ts.

Lucide has almost 2,000 icons, and each would otherwise become its own file in your JAR. In the notes example, this takes the frontend build from 6,180 files and 11 MB down to 120 files and 1.8 MB. The LucideIcon enum and the TypeScript type still list every icon, so anything stored or sent stays valid.

A list of icons in your own code is found the same way, since each name is a string:

ts
import type { LucideIcon } from '#api';

const choices: LucideIcon[] = ['SquareCheck', 'Bug', 'Lightbulb', 'Rocket'];

In development ​

In development, an icon that isn't in the list yet still shows, with a console hint to run svelteSync. A production build checks the list and fails with "Run svelteSync" when an icon is missing, so nothing silently disappears. svelteDevAll syncs on every Kotlin change.

Keep every icon ​

If icon names come from somewhere the scan can't see, such as a database your users fill or an icon picker, keep all icons:

kotlin
svelte {
    libraries {
        lucide {
            allIcons()
        }
    }
}
SettingDefaultWhat it does
allIcons()offBuilds every Lucide icon into the frontend, not only the ones the scan finds

Images ​

images() adds SvelteKit's @sveltejs/enhanced-img. Keep pictures next to your code, for example in frontend/src/lib/assets, and use enhanced:img instead of img:

svelte
<enhanced:img src="#lib/assets/hero.png" alt="Our team" sizes="(min-width: 768px) 65ch, 100vw" />

What the build makes of it ​

At build time, every image becomes AVIF and WebP in several widths, plus a fallback in the original format, inside a <picture> with srcset, width and height.

  • Browsers download only the size and format they need.
  • The layout doesn't jump while the image loads, because the size is known.
  • In the notes example, a 339 KB PNG becomes an 8 KB AVIF for a laptop screen.
  • The files land in _app/immutable/, so browsers cache them for a year like any other hashed asset.

sizes is the standard HTML attribute that tells the browser how wide the image is shown, so it can pick the right file.

Images in static ​

Files in frontend/static/ are copied as they are, because nothing in the build knows where they are used. Move images there to src/lib/assets to have them optimized.

Full example ​

A task form with an icon picker, where the icon is a typed field of the DTO, and a start page with a hero image. This is how the showcase example does it.

kotlin
import io.github.nijasc.ktorsvelte.LucideIcon

@Serializable
data class TaskInput(
    val title: String,
    val icon: LucideIcon = LucideIcon.SquareCheck,
)

@Serializable
data class Task(
    val id: Long,
    val title: String,
    val icon: LucideIcon,
)
svelte
<script lang="ts">
    import type { LucideIcon, TaskInput } from '#api';
    import Icon from '#icon';

    let { draft = $bindable() }: { draft: TaskInput } = $props();

    const icons: LucideIcon[] = ['SquareCheck', 'Bug', 'Lightbulb', 'Rocket', 'Flame', 'Package', 'Star'];
</script>

<fieldset>
    <legend class="mb-1">Icon</legend>
    <div class="flex flex-wrap gap-2">
        {#each icons as icon (icon)}
            <label class="btn btn-sm" class:btn-primary={draft.icon === icon}>
                <input class="sr-only" type="radio" name="task-icon" value={icon} bind:group={draft.icon} />
                <Icon name={icon} size={16} />
                <span class="sr-only">{icon}</span>
            </label>
        {/each}
    </div>
</fieldset>
svelte
<script lang="ts">
    import type { Task } from '#api';
    import Icon from '#icon';

    let { task }: { task: Task } = $props();
</script>

<a class="link flex items-center gap-2 font-semibold" href="/tasks/{task.id}">
    <Icon name={task.icon} size={18} />
    {task.title}
</a>
svelte
<script lang="ts">
    import Icon from '#icon';
</script>

<section class="grid items-center gap-8 md:grid-cols-2">
    <div>
        <h1 class="text-4xl font-bold">A team board in one JAR</h1>
        <a class="btn btn-primary mt-6" href="/board"><Icon name="LayoutDashboard" size={18} /> Open the board</a>
    </div>
    <enhanced:img
        class="rounded-box h-auto w-full"
        src="#lib/assets/hero.png"
        alt="Ktor and SvelteKit working together"
        sizes="(min-width: 768px) 28rem, 100vw"
    />
</section>

The seven icons of the picker, LayoutDashboard, and every LucideIcon.X in your Kotlin code are found by the scan, so they are in the build. A task stored with any other icon still loads in development, and a production build tells you to run svelteSync.

Use cases ​

  • Users pick an icon for a project, a label or a category: store it as a LucideIcon, and it is validated on the way in.
  • Navigation items with icons, defined once next to typed routes.
  • A marketing or start page with large pictures: enhanced:img.
  • Icons chosen from data you do not control, such as a user-filled table: allIcons().

Good to know ​

Smaller JARs

Without the used-icon scan, every Lucide icon would be a file in your JAR. With it, only the icons you use are built. Turn on allIcons() only when names come from data.

Image processing

Processing uses sharp, which comes with prebuilt binaries for Windows, macOS and Linux. The first build with many large images takes longer, and later builds reuse Vite's cache.

Documentation for ktor-svelte 1.4.0. Released under the Apache 2.0 license.