Skip to content

Components ​

components() generates Svelte components for the things a ktor-svelte app does all the time: form fields with validation, date inputs, enum selects, a paged table, file uploads, an error page, theme and language switches. Every project with generated files also gets helpers for modals, confirmations and toasts, a guide for coding assistants and lint rules.

Gradle Generated files

This page is part of Frontend libraries.

Quick start ​

kotlin
svelte {
    libraries {
        daisyUi()
        components()
    }
}
svelte
<script lang="ts">
    import { TaskInput } from '#api';
    import Field from '#components/Field.svelte';

    let draft = $state(TaskInput.empty());
</script>

<Field label="Title" bind:value={draft.title} bounds={TaskInput.bounds.title} />

How the components work ​

components() generates Svelte components into src/lib/ktor-svelte/components, imported as #components/.... They are the pieces that exist because of something the plugin already generates: a component here is a few lines of markup over a generated helper, written once. They use DaisyUI's classes when daisyUi is on, and plain class names with a minimal style otherwise.

The files belong to the plugin and are rewritten by svelteSync. For a different look, write your own component on the same helper. The generated ones are short enough to copy as a start.

The components import from #api, so they need generateTs = true on the server.

ComponentGenerated whenWhat it does
Fieldcomponents()A label, an input, a hint and its validation errors
DateInput, DateTimeInputcomponents()Date and date-time inputs bound to the API's date text, null when empty
EnumSelectcomponents()A select over a generated enum
DataTablecomponents()A table over a route that returns Page<T>
FileDropcomponents()A drop area with progress for an upload route
ErrorPagecomponents()The page SvelteKit shows when a page fails, with +error.svelte
NavigationProgresscomponents()A thin bar while a navigation waits
ThemeTogglecomponents() and daisyUiSwitches the theme
LocaleSwitchcomponents() and i18nSwitches the language
TimeAgocomponents() and i18n"3 minutes ago" that stays current
HelperGenerated whenWhat it does
modalAny generated filesOpens a <dialog> and returns its result
confirmedAny generated filesAsks before a call
toasttoasts()Shows a short message in the corner
AGENTS.mdAny generated filesA guide for coding assistants
eslint.jsAny generated filesLint rules for ktor-svelte mistakes

Field ​

One form field: its label, the input, an optional hint, and the validation errors.

svelte
<script lang="ts">
    import { NoteInput } from '#api';
    import Field from '#components/Field.svelte';
    import { formState } from '#lib/api/form-state.svelte.ts';

    const form = formState<NoteInput>(NoteInput.empty(), { validate: NoteInput.validate });
</script>

<Field label="Title" bind:value={form.draft.title} bounds={NoteInput.bounds.title} errors={form.errors.title} hint="Shown in the list." />
<Field label="Text" multiline rows={4} bind:value={form.draft.body} errors={form.errors.body} />
PropMeaning
labelThe text of the <label>, tied to the input. Required
bind:valueThe value, as with an <input>
boundsThe limits from the DTO, such as NoteInput.bounds.title. They become required, maxlength and the like
errorsThe messages for this field, from validate() or from a 422
hintA line under the input, announced with it by screen readers
multilineRenders a <textarea>
idThe input's id. Without it, one is made up
classAdded to the wrapper
controlA snippet for a control that is not a plain input, see below

Everything else, such as type, autocomplete, placeholder or rows, goes to the input unchanged. Underneath it is the field action, so errors appear and disappear the same way as with use:field.

Password and email fields ​

svelte
<Field label="Email" type="email" autocomplete="email" bind:value={login.email} errors={errors.email} />
<Field
    label="New password"
    type="password"
    autocomplete="new-password"
    bind:value={password.next}
    bounds={PasswordChange.bounds.next}
    errors={errors.next}
    hint="At least {PasswordChange.bounds.next.minlength} characters."
/>

A custom control ​

For a control that is not a plain input, pass it as the control snippet. It gets the id the label points at and the options for use:field, and the label, hint and errors stay as they are:

svelte
<Field label="Color" errors={form.errors.color}>
    {#snippet control({ id, options })}
        <input {id} type="color" bind:value={form.draft.color} use:field={options} />
    {/snippet}
</Field>

DateInput and DateTimeInput ​

A date from the API is an IsoDate, text such as 2026-12-24, and a field that may be empty is null. A plain <input type="date"> gives '' for empty and plain text otherwise, so pages convert by hand. DateInput binds to the value as it is:

svelte
<script lang="ts">
    import DateInput from '#components/DateInput.svelte';
    import DateTimeInput from '#components/DateTimeInput.svelte';
</script>

<DateInput label="Due on" bind:value={form.draft.dueOn} errors={form.errors.dueOn} />
<DateTimeInput label="Starts at" bind:value={form.draft.startsAt} />
<DateTimeInput label="Opens at" local bind:value={form.draft.opensAt} />

Both take the props of Field (label, bounds, errors, hint, id, class and any input attribute such as min or max), and an empty input is null.

ComponentKotlin typeWhat it sends
DateInputLocalDateThe date as typed, such as 2026-12-24
DateTimeInputInstantShows the moment in the visitor's own time zone and stores it as the UTC text the server expects
DateTimeInput localLocalDateTimeThe wall-clock text as typed, with no time zone

MaskedInput ​

A text field that formats while you type, for values people read in groups: phone numbers, IBANs, dates and money. The field shows the friendly form, and the bound value is the clean one your API expects:

svelte
<script lang="ts">
    import MaskedInput from '#components/MaskedInput.svelte';
</script>

<MaskedInput label="Phone" mask="phone" bind:value={form.draft.phone} />
<MaskedInput label="IBAN" mask="iban" bind:value={form.draft.iban} />
<MaskedInput label="Birthday" mask="date" bind:value={form.draft.birthday} />
<MaskedInput label="Price" mask="money" bind:value={form.draft.price} />
maskYou see while typingBound value
phone+49 301 234 567, 0301 2345 67+49301234567: digits and a leading +
ibanDE89 3704 0044 0532 0130 00, in capitalsDE89370400440532013000
date24.12.2026 in German, 12/24/2026 in American English2026-12-24, an IsoDate, once the date is complete and real; null before
money1.234.567,8 in German, 1,234,567.8 in English1234567.8, a plain decimal for a Decimal field
PropDefaultWhat it does
labelrequiredThe label, as for Field
maskrequired'phone', 'iban', 'date', 'money', or your own Mask
valueThe clean value, bind:value; null while the field is empty or a date is incomplete
localethe page's langWhich order and separators date and money use
bounds, errors, hint, classAs for Field
  • The caret stays after the same character you typed, even when a space or a separator is added in front of it.
  • The field sets inputmode, so phones show the number or phone keyboard.
  • Money keeps a decimal separator you just typed, so 1234, stays on screen while the value is 1234. It never goes through a JavaScript number, so large amounts keep every digit.
  • When you leave the field, a complete value is shown in its tidy form. An incomplete date stays as typed, with null as the value, so the form's validation can say it is required.
  • For another format, pass an object with show(clean), retype(typed), clean(typed), keeps(character) and inputMode, the same shape masks.ts exports for the four built-in ones.

ErrorSummary ​

A box that lists every error of a form, each a link that moves focus to its field. Put it above or below the submit button of a long form:

svelte
<script lang="ts">
    import ErrorSummary from '#components/ErrorSummary.svelte';
</script>

<ErrorSummary errors={form.errors} labels={{ name: 'Name', email: 'Email', password: 'Password' }} />
PropDefaultWhat it does
errorsrequiredThe errors per field, usually form.errors
labels{}The text to show for each field; the field name when there is none
titlePlease check these fields:The heading of the box; pass a message for other languages
classMore classes for the box
  • It shows nothing while there are no errors, and is announced as an alert when it appears.
  • A link finds its field by id first, then by name, so give the fields an id or name equal to the property, as <Field id="email" ...> does.
  • With DaisyUI it is an alert alert-error; without, it has a small style of its own.

PasswordStrength ​

A meter and a checklist under a password field, driven by the same rule the server enforces with @Rule.StrongPassword. Nobody has to guess what "strong" means, and the browser can never accept a password the server will refuse:

svelte
<script lang="ts">
    import Field from '#components/Field.svelte';
    import PasswordStrength from '#components/PasswordStrength.svelte';
</script>

<Field label="New password" type="password" bind:value={form.draft.password} errors={form.errors.password} />
<PasswordStrength password={form.draft.password} />
PropDefaultWhat it does
passwordrequiredThe password typed so far
requirements{}Your own text per requirement, keyed by the English text, such as { 'a digit': m.passwordDigit() }
labelPassword strengthAccessible name of the meter
strongTextStrong enough.Announced once every rule is met
classMore classes

The rules come from the generated client, so you can also use them without the component:

ts
import { passwordMessage, passwordRules, passwordStrength } from '#api';

const strength = passwordStrength('Correct1horse');
strength.score;
strength.strong;
strength.missing.map((rule) => rule.requirement);
NameWhat it is
passwordRulesEvery part of the rule: pattern and requirement, such as at least 10 characters, a lowercase letter, an uppercase letter, a digit
passwordStrength(password)met, missing, score from 0 to 1, and strong when nothing is missing
passwordMessageThe message the server answers with when the rule fails
  • Each rule is shown with a + or a - and a color, so it does not depend on color alone.
  • Screen readers hear the meter's value and, once, that the password is strong enough, instead of every keystroke.
  • Use it only for a property with @Rule.StrongPassword; for your own rule, write your own list.

NumberInput ​

A number field that groups digits and uses the decimal separator of the visitor's language, and never rounds. Bind it to a Decimal for money and exact amounts, or to a number:

svelte
<script lang="ts">
    import NumberInput from '#components/NumberInput.svelte';
</script>

<NumberInput label="Price" bind:value={form.draft.price} />
<NumberInput label="Rate" bind:value={form.draft.rate} fractionDigits={4} />
<NumberInput label="Seats" bind:value={form.draft.seats} fractionDigits={0} number />
PropDefaultWhat it does
valuebind:value; a Decimal string such as "1234.5", or a number; null while empty
fractionDigits2How many digits after the separator can be typed; 0 for whole numbers, where the separator is not accepted at all
numberfalseBind a number instead of a string; also on by itself when the value already is a number
localethe page's langWhich separators to use
label, bounds, errors, hint, classAs for Field
  • In German, typing 1234567,8 shows 1.234.567,8 and binds "1234567.8"; in English the same amount is 1,234,567.8.
  • A Decimal never goes through a JavaScript number, so 12345678901234567890.1234 keeps every digit. Use number only for values that fit a double, such as counts.
  • The keyboard on phones is the decimal one, and the caret stays where you are typing, as in MaskedInput, which this component builds on.

A ready breadcrumb trail for the open page, built from the titles your pages declare in _nav. It comes with components() when routes() is on too:

svelte
<script lang="ts">
    import Breadcrumbs from '#components/Breadcrumbs.svelte';

    let { data } = $props();
</script>

<Breadcrumbs current={data.task.title} />

On /admin/tasks this shows "Home / Admin / All tasks", each part a link except the last.

PropDefaultWhat it does
currentThe name of the open page, such as a record's title. It replaces the page's own title, or is added when the page has none, as for /tasks/[id]
labels{}Other names for parts of the trail, keyed by their link, such as { '/projects/7': project.name }
labelBreadcrumbThe accessible name of the <nav>; pass a message for other languages
classMore classes
  • The trail follows the page's place in your routes: every parent folder with a title is a step. Groups such as (app) are left out.
  • It shows nothing on a page with no parents, so you can put it in a layout.
  • The current page is marked with aria-current="page" and is not a link.
  • With DaisyUI it uses the breadcrumbs class; without, a small style with / between the parts.

A side menu for a section of your app. On wide screens it can collapse to icons, and remembers that; on small screens it turns into a drawer behind a "Menu" button:

svelte
<script lang="ts">
    import Sidebar from '#components/Sidebar.svelte';
    import { routes } from '#routes';

    let { children } = $props();
</script>

<Sidebar
    items={[
        { href: routes.admin(), label: 'People', icon: 'Users' },
        { href: routes.adminTasks(), label: 'All tasks', icon: 'ListChecks' }
    ]}
    label="Admin sections"
>
    {@render children()}
</Sidebar>

Put it in the +layout.svelte of the section, as above, and every page below gets it.

PropDefaultWhat it does
itemsrequired{ href, label, icon? } per link; icon is a typed Lucide name when lucide() is on
childrenrequiredThe page content, shown next to the menu
labelSectionsThe accessible name of the <nav>
rememberktor-svelte-sidebarThe localStorage key for the collapsed state; give each sidebar its own
collapseText, expandText, menuTextCollapse, Expand, MenuButton texts, for other languages
  • Collapsed, the links show only their icons, or the first letter of the label without Lucide. The label stays readable for screen readers and shows as a tooltip.
  • The collapsed state is read after the page has loaded, so the server and the browser render the same first.
  • Below 768 pixels wide, the menu is hidden. The "Menu" button opens it as a drawer over the page; Escape, a click on the backdrop or opening a link closes it.
  • The link to the open page has aria-current="page".

FocusHeading ​

After a navigation inside the app, SvelteKit puts the focus back at the top of the document. Keyboard and screen reader users then start from the very beginning on every page. FocusHeading moves the focus to the new page's heading instead, so they land where the content starts and hear its name:

svelte
<script lang="ts">
    import FocusHeading from '#components/FocusHeading.svelte';

    let { children } = $props();
</script>

<FocusHeading />
{@render children()}

Put it once in your root +layout.svelte.

PropDefaultWhat it does
selectormain h1, h1Which element gets the focus: the first match on the new page
  • It does nothing on the first page load, and nothing for links to an anchor such as #comments, where the browser's own jump is right.
  • The heading gets tabindex="-1", so it can take the focus without becoming a stop in the tab order. The page does not scroll.
  • SvelteKit's own announcer still tells screen readers the new page title.

EnumSelect ​

A <select> over a generated enum object:

svelte
<script lang="ts">
    import { Status } from '#api';
    import EnumSelect from '#components/EnumSelect.svelte';
</script>

<EnumSelect label="Status" options={Status} bind:value={form.draft.status} labels={{ TODO: 'To do', DONE: 'Done' }} placeholder="Any" />

It lists every value of the enum, so a value added in Kotlin appears after the next svelteGenerateTs. The bound value has the enum's type, so no cast is needed.

PropMeaning
labelThe label. Required
optionsThe generated enum object, such as Status
bind:valueThe chosen value, or null
labelsThe text to show per value, as text or as a function for translations. A value without one shows its name
placeholderAdds a first option that stands for null
bounds, errors, hint, id, classAs on Field

Translated labels are functions, so they follow the language:

svelte
<script lang="ts">
    import { Priority } from '#api';
    import EnumSelect from '#components/EnumSelect.svelte';
    import { m } from '#i18n';

    const priorityLabels: Record<Priority, () => string> = {
        LOW: m.priorityLow,
        NORMAL: m.priorityNormal,
        HIGH: m.priorityHigh
    };
</script>

<EnumSelect label={m.fieldPriority()} options={Priority} labels={priorityLabels} bind:value={draft.priority} />

DataTable ​

A table over any route that returns Page<T>. It loads the pages, and shows a line while it loads, when there is nothing, and when a load failed, with a button to try again.

svelte
<script lang="ts">
    import { api } from '#api';
    import DataTable from '#components/DataTable.svelte';

    let search = $state('');
</script>

<input type="search" bind:value={search} aria-label="Search" />
<DataTable
    load={api.notes.list}
    query={{ search, limit: '20' }}
    key={(note) => note.id}
    columns={[
        { key: 'title', label: 'Title' },
        { key: 'createdAt', label: 'Created', text: (note) => new Date(note.createdAt).toLocaleDateString() },
        { id: 'size', label: 'Size', text: (note) => `${note.body.length} characters` }
    ]}
/>

load is the generated function of the route, and the rows have the type it returns. So a column's key must be a property of the item, a typo fails svelteCheck, and text gets the typed item. A column that is not one property has an id and a text instead.

PropMeaning
loadThe generated function of a route that returns Page<T>
columnsThe headers, and what each cell shows
queryThe query parameters besides the cursor. When they change, the table loads again from the start
keyA stable id per row, such as (note) => note.id
paging'more' (the default) adds rows with a Load more button. 'pages' shows one page with Previous and Next
firstA first page that a load function already fetched, so the table does not fetch it again
captionA caption for the table
rowA snippet that renders the cells of one row, see below
empty, loading, more, previous, next, retryThe texts, in English unless given: "Nothing here yet.", "Loading", "Load more", "Previous", "Next", "Try again"
classAdded to the wrapper

Choosing columns ​

With chooser, a "Columns" menu above the table lets people hide columns and change their order. With remember, the choice is kept in the browser for next time:

svelte
<DataTable load={api.tasks.list} columns={columns} chooser remember="admin-tasks" />
PropDefaultWhat it does
chooserfalseShows the menu with a checkbox per column and buttons to move it up or down
rememberA name for this table. The order and the hidden columns are kept in localStorage under ktor-svelte-table:<name>
columnsLabel, moveUp, moveDownColumns, Up, DownThe texts of the menu, for other languages
  • The last visible column cannot be hidden.
  • A column you add to columns later shows up at the end; one you remove is forgotten.
  • The move buttons say which column they move, such as "Up: Status", for screen readers.
  • A custom row gets the visible columns as its second argument, {#snippet row(task, columns)}, so its cells can follow the choice.

Selecting rows and acting on them ​

Give the table actions, and every row gets a checkbox. A bar above the table shows how many are chosen and a button per action, which calls your function for each chosen row:

svelte
<DataTable
    load={api.tasks.list}
    key={(task) => task.id}
    {columns}
    actions={[
        { label: 'Mark as done', run: (task) => api.tasks.status(task.id, { status: 'DONE' }) },
        { label: 'Delete', run: (task) => api.tasks.delete(task.id), confirm: 'Delete the chosen tasks?' }
    ]}
/>
PropDefaultWhat it does
actions[]{ label, run, confirm? } per action; run is called once per chosen row, one after the other
keyNeeded to keep choices across pages and for "Select every page"
selectRowSelect all on this page: <first column>The accessible name of a row's checkbox
selectPage, selectEverything, clearSelectionSelect all on this page, Select every page, ClearButton and checkbox texts
selectedText, workingText, doneText2 selected, Working: 1 of 2, Done: 2 of 2 worked.Functions that build the status texts, for other languages
  • The checkbox in the header chooses every row on the page, and shows a mixed state when only some are chosen.
  • "Select every page" loads the remaining pages and chooses everything, so an action can run over the whole list, not only what is visible.
  • While an action runs, the bar counts up and the checkboxes are locked. When it ends, the bar says how many calls worked, the choice is cleared and the table reloads.
  • A failing call does not stop the others; with toasts on, each failure is shown too.
  • confirm asks with the browser's dialog before the action starts.

Sorting by a click on the header ​

Mark a column with sort, and its header becomes a button. The first click sorts ascending, the second descending, the third goes back to the order of the route:

svelte
<DataTable
    load={api.tasks.list}
    columns={[
        { key: 'title', label: 'Title', sort: true },
        { key: 'createdAt', label: 'Created', sort: 'created' }
    ]}
    sortParam="sort"
/>
What happens
With sortParamThe table asks the route again with ?sort=title or ?sort=-title (a leading - for descending), from the first page. Use this for lists with many pages; the route decides how to sort. sort: 'created' sends that name instead of the column's key
Without sortParamThe rows that are loaded are sorted in the browser, numbers as numbers and text in the visitor's language. This suits short lists that fit on one page; on a list with more pages, only the loaded rows are sorted
  • The header gets aria-sort (ascending or descending), and a small ^ or v shows the direction.
  • With sortParam, the route reads the value like any other query parameter, such as call.queryParameters["sort"]; list it in describe to have it typed.

When there is nothing to show ​

An empty table is either a fresh start or a filter that matches nothing, and people need to hear different things. The table tells them apart by its query: any value other than cursor and limit counts as a filter.

svelte
<DataTable
    load={api.tasks.list}
    query={{ search }}
    {columns}
    empty="No tasks yet."
    noResults="No task matches your search."
>
    {#snippet emptyAction()}
        <a class="btn btn-primary" href={routes.tasksNew()}>Create the first task</a>
    {/snippet}
</DataTable>
PropDefaultWhen it shows
emptyNothing here yet.No rows and no filter
emptyActionA snippet under empty, such as a button that creates the first item; not shown for a filter
noResultsNothing matches this filter.No rows while a filter is set
filteredworked out from querySet it yourself when the filter lives elsewhere, for example in the route's path

The block carries data-empty="none" or data-empty="filtered", handy for tests and styles.

Placeholder rows while loading ​

While the first page loads, the table shows a few grey rows shaped like its columns instead of an empty box, so the page does not jump when the data arrives. Later loads keep the rows you already see.

svelte
<DataTable load={api.tasks.list} {columns} skeletonRows={5} />
  • skeletonRows sets how many, 3 by default, and 0 turns them off.
  • The rows are aria-hidden; screen readers still hear the loading text.
  • With DaisyUI they use its skeleton class; without, a small pulsing bar of their own. Each carries data-skeleton.

Long lists ​

With virtual, the table sits in a box of its own height, renders only the rows in view, and loads the next page when you scroll near the end. Thousands of rows stay as quick as twenty:

svelte
<DataTable load={api.tasks.list} query={{ limit: 50 }} key={(task) => task.id} {columns} virtual={{ rowHeight: 40, height: '28rem' }} />
OptionDefaultWhat it does
rowHeightrequiredThe height of one row in pixels; every row gets exactly this height
height24remThe height of the scrolling box, any CSS length
overscan5Rows rendered above and below the visible ones, so fast scrolling does not show gaps
  • The paging buttons go away; scrolling is the paging.
  • The table keeps aria-rowcount with the number of loaded rows, and each row its aria-rowindex, so screen readers still know where they are.
  • Keep cells to one line, since rows have a fixed height. For text that wraps, use normal paging instead.
  • Rows that can be chosen and sorted work the same; sorting in the browser sorts the rows loaded so far.

Opening a row, with the mouse or the keyboard ​

Give the table onopen, and each row opens with a click or with Enter. The rows become one stop in the tab order, and the arrow keys move between them:

svelte
<DataTable load={api.tasks.list} {columns} onopen={(task) => goto(routes.tasksId({ id: task.id }))} />
KeyWhat it does
TabReaches the table once, on the last row you were on
Arrow down, Arrow upThe next or the previous row
Home, EndThe first or the last loaded row
Page down, Page upTen rows on, or a box height with virtual
EnterCalls onopen with that row
  • Clicks and keys on controls inside a row, such as the selection checkbox or a link in a custom cell, do their own thing and do not open the row.
  • With virtual, moving to a row that is not rendered scrolls to it first.
  • The focused row shows an outline; with DaisyUI it also highlights on hover.

Cells with markup ​

For cells with markup, such as a link or a button, pass a row snippet. It renders the cells of one row, and columns then only gives the headers:

svelte
<DataTable load={api.notes.list} columns={[{ key: 'title', label: 'Title' }, { id: 'open', label: '' }]}>
    {#snippet row(note)}
        <td>{note.title}</td>
        <td><a href={routes.notesId({ id: note.id })}>Open</a></td>
    {/snippet}
</DataTable>

Reloading ​

After a change elsewhere on the page, bind:this the table and call its reload():

svelte
<script lang="ts">
    let table = $state<{ reload(): Promise<void> }>();

    async function remove(id: number) {
        await api.notes.delete(id);
        await table?.reload();
    }
</script>

<DataTable bind:this={table} load={api.notes.list} columns={[{ key: 'title', label: 'Title' }]} />

A server-rendered first page ​

ts
export const load: PageLoad = async (event) => {
    return { first: await apiWith(event).notes.list({ limit: '20' }) };
};
svelte
<DataTable load={api.notes.list} query={{ limit: '20' }} first={data.first} columns={[{ key: 'title', label: 'Title' }]} />

The route's pages are cursors, so there are no page numbers: the table can go forward and back, not jump.

FileDrop ​

A drop area with a file input for an upload route. Files can be dropped on it or chosen, and each one is shown while it travels: a preview for images, the name and size, a progress bar, and the reason when it was refused.

svelte
<script lang="ts">
    import { api, uploadRules } from '#api';
    import FileDrop from '#components/FileDrop.svelte';

    let documents = $state<StoredFile[]>([]);
</script>

<FileDrop
    label="Add documents"
    hint="PDF or images, up to 5 MiB each."
    multiple
    rules={uploadRules['documents.create']}
    upload={(file, options) => api.documents.create({ file }, options)}
    onuploaded={(stored) => (documents = [...documents, stored])}
/>
PropMeaning
uploadSends one file. Pass the route's generated function, and hand it the options it is given: they carry the progress
labelThe label of the file input. Required
rulesThe route's entry in uploadRules. Its types become the input's accept
hintA line under the input
multipleTakes several files. They are sent one after another, each in its own request
onuploadedCalled with the route's answer and the file, after each one that went through
problemTurns a failed upload into the text to show, for your own wording or language. Without it the server's message is shown
uploadingThe start of the progress bar's accessible name, Uploading unless given
disabled, id, classAs on an input

The route's rules are checked before a file is sent, as with any call to the generated function, so a file that is too large or of the wrong type is refused at once and nothing is uploaded. A file that went through leaves the list, and one that failed stays with its reason until the next files are chosen.

Translated problems ​

The showcase attaches files to a task and names the problem in the visitor's language:

svelte
<script lang="ts">
    import { api, errorMessage, isUploadError, uploadRules, type Attachment } from '#api';
    import FileDrop from '#components/FileDrop.svelte';
    import { m } from '#i18n';

    let { task, attachments = $bindable() }: { task: Task; attachments: Attachment[] } = $props();

    function uploadProblem(error: unknown): string {
        if (!isUploadError(error)) return errorMessage(error);
        return error.body.code === 'upload.tooLarge' ? m.problemFileTooLarge() : m.problemFileType();
    }
</script>

<FileDrop
    label={m.attachmentsAdd()}
    uploading={m.attachmentsUploading()}
    multiple
    rules={uploadRules['tasks.attachments']}
    upload={(file, options) => api.tasks.attachments(task.id, { file }, options)}
    problem={uploadProblem}
    onuploaded={(stored) => (attachments = [...attachments, ...stored])}
/>

ErrorPage ​

components() also writes src/routes/+error.svelte, the page SvelteKit shows when a page cannot be shown. It is three lines around <ErrorPage />, which shows:

  • the status, such as 404
  • the message: the one the server sent in the error body when a call failed, the one you passed to error(...), and otherwise a sentence for 404, 403, 401 or anything else
  • the request ID for a status of 500 and above, so a visitor can quote it and you can find the request in the log
  • a link back to the start page, home="/" unless you pass another
PropDefaultMeaning
home"/"Where the link back leads

A load function no longer has to translate a failed call into a page error. Let it throw:

ts
export const load: PageLoad = async (event) => {
    return { note: await apiWith(event).notes.get(event.params.id) };
};

When the server answers 404 with { "message": "That note does not exist." }, the error page shows 404 and that message. This works through handleError in src/hooks.client.ts, which svelteSync writes. It puts the status, message, request ID and error code of a failed call into page.error, typed through App.Error, so your own components can read page.error.code too.

The sentences are English until your messages have their keys. With i18n on, add the ones you want translated and run svelteSync:

KeyDefault
error-not-foundThis page does not exist.
error-forbiddenYou are not allowed to see this page.
error-sign-inSign in to see this page.
error-failedSomething went wrong. Please try again.
error-request-idRequest ID:
error-homeBack to the start page

Your own files win. If src/routes/+error.svelte exists and is not the generated one, it is left alone, and you can use <ErrorPage /> inside it or not. To change the generated one, remove its first line, and it is yours. The same goes for src/hooks.client.ts when toasts() is off: keep your own and add export { handleError } from '#lib/ktor-svelte/errors.ts'; to it.

An error page of your own that keeps the generated content, inside the app's frame:

svelte
<script lang="ts">
    import ErrorPage from '#components/ErrorPage.svelte';
    import { page } from '$app/state';
</script>

<div class="mx-auto max-w-xl py-16 text-center">
    <ErrorPage home="/board" />
    {#if page.error?.code === 'NotYours'}
        <p class="mt-4">Ask the person who created it to share it with you.</p>
    {/if}
</div>

ThemeToggle and LocaleSwitch ​

The theme and i18n helpers already know the themes and languages you configured. These two components put them on the page, so a new app has both switches from the start:

svelte
<script lang="ts">
    import LocaleSwitch from '#components/LocaleSwitch.svelte';
    import ThemeToggle from '#components/ThemeToggle.svelte';
</script>

<ThemeToggle />
<LocaleSwitch />

ThemeToggle is generated when daisyUi is on. With two themes it is a button that flips between them, with more it is a <select>. It applies the theme at once and remembers it, as setTheme does.

LocaleSwitch is generated when i18n is on. It lists each language under its own name, such as English and Deutsch, and switches with setLocale.

PropDefaultMeaning
labelTheme, LanguageThe accessible name. Pass a translated one
labelsnoneAn object from theme or language to the text to show, to name single entries yourself
idnoneThe id of the button or select
classnoneAdded to the button or select
svelte
<ThemeToggle id="theme" class="w-36" label={m.settingsTheme()} labels={{ 'shadcn-light': 'Light', 'shadcn-dark': 'Dark' }} />
<LocaleSwitch id="locale" class="w-28" label={m.settingsLanguage()} />

TimeAgo ​

"3 minutes ago", "yesterday", in the visitor's language, and kept current while the page stays open. Generated when i18n is on.

svelte
<script lang="ts">
    import TimeAgo from '#components/TimeAgo.svelte';
</script>

<p>{comment.author.name} <TimeAgo class="opacity-70" value={comment.createdAt} /></p>
PropMeaning
valueAn ISO date-time text, or a Date
classAdded to the <time> element

It renders a <time> element with the exact date and time as its tooltip, and every instance on the page is refreshed by one shared timer, twice a minute. The words come from timeAgo.

A thin bar at the top of the page while SvelteKit navigates, which includes the time a load function waits for the server. Without it, a click on a link to a slow page looks like nothing happened. Put it in the root layout, once:

svelte
<script lang="ts">
    import NavigationProgress from '#components/NavigationProgress.svelte';

    let { children } = $props();
</script>

<NavigationProgress />
{@render children()}
PropDefaultMeaning
delay150Milliseconds a navigation must take before the bar appears, so quick ones do not flash
labelLoading pageThe accessible name of the progress bar
classnoneAdded to the bar
  • Its color is the theme's primary color with DaisyUI, and the text color otherwise. Set the CSS variable --ktor-svelte-progress to choose another.
  • It is announced as a progress bar with the name label.
  • With "reduce motion" set in the visitor's system, it is a still line.

Modals ​

A <dialog> normally needs a bind:this, a showModal() and a way to learn how it was closed. modal() from #lib/ktor-svelte/modal.ts is those three:

svelte
<script lang="ts">
    import { modal } from '#lib/ktor-svelte/modal.ts';

    const rename = modal<string>();
    let name = $state('');

    async function askForName() {
        const chosen = await rename.open();
        if (chosen) console.log('renamed to', chosen);
    }
</script>

<button onclick={askForName}>Rename</button>

<dialog class="modal" use:rename.attach>
    <div class="modal-box">
        <input bind:value={name} aria-label="New name" />
        <button onclick={() => rename.close(name)}>Save</button>
        <button onclick={() => rename.close()}>Cancel</button>
    </div>
</dialog>
MemberMeaning
modal<T>(options)Makes a modal whose result has the type T
attachThe action for the <dialog>: use:rename.attach
open()Shows the dialog and returns a promise of the result
close(result)Closes it, and the promise resolves with result
isOpenWhether it is showing
closeOnBackdrop: falseAn option that keeps a click beside the box from closing it

open() resolves with what close(result) was given, or with undefined when the dialog was closed any other way: close() without a value, Escape, or a click beside the box. Calling open() while it is already open returns the same promise.

The markup is yours, so it works with DaisyUI's modal classes, as above, and with a plain <dialog>.

Confirm before a call ​

To only ask a yes or no question before a call, use confirmed from #lib/ktor-svelte/confirm.ts, which brings its own dialog:

ts
import { confirmed } from '#lib/ktor-svelte/confirm.ts';

const deleted = await confirmed('Delete this note?', () => api.notes.delete(id), {
    details: 'It cannot be restored.',
    confirm: 'Delete',
    danger: true
});
OptionMeaning
detailsA line under the question
confirm, cancelThe button labels. They default to confirmMessages.confirm and confirmMessages.cancel
dangerA red confirm button, with the focus on Cancel

With DaisyUI on, the question is a modal in your theme that stays open while the call runs and shows its error. Without DaisyUI it is the browser's own confirm. The full description is in Ask before a call.

Toasts ​

With toasts() on, failed API calls show up as toasts by themselves, see Show errors automatically. You can also show your own, from #lib/ktor-svelte/toasts.ts:

ts
import { toast } from '#lib/ktor-svelte/toasts.ts';

toast('Saved.', { kind: 'success' });
toast('Note archived.', { action: { label: 'Undo', run: restore } });
toast('We just shipped an update.', { duration: 0, action: { label: 'Reload', run: () => location.reload() } });
OptionDefaultMeaning
kind'info''info', 'success', 'warning' or 'error'
duration5000Milliseconds until it goes away. 0 keeps it until it is closed
actionnoneA button: { label, run }. A click runs it and closes the toast
  • With DaisyUI, toasts are DaisyUI alerts in your theme. Otherwise they bring their own small style.
  • Errors and warnings are announced to screen readers as alerts, the others politely.
  • Change the built-in texts, such as the network message or the close button's name, through toastMessages.
  • The server can send toasts too, with call.toast(...), see Toasts from the server.

Full example ​

A "new task" form built from generated components, with validation in the browser and from the server, a confirmation before deleting, and toasts. It uses the showcase's TaskInput:

kotlin
import io.ktor.openapi.JsonSchema

@Serializable
data class TaskInput(
    @Trim
    @JsonSchema.MinLength(1)
    @JsonSchema.MaxLength(120)
    val title: String,
    @JsonSchema.MaxLength(4000)
    val description: String = "",
    val priority: Priority = Priority.NORMAL,
    val dueOn: LocalDate? = null,
    val remindAt: Instant? = null,
)
svelte
<script lang="ts">
    import { goto } from '$app/navigation';
    import { api, Priority, TaskInput } from '#api';
    import DateInput from '#components/DateInput.svelte';
    import DateTimeInput from '#components/DateTimeInput.svelte';
    import EnumSelect from '#components/EnumSelect.svelte';
    import Field from '#components/Field.svelte';
    import { m } from '#i18n';
    import { formState } from '#lib/api/form-state.svelte.ts';
    import { confirmed } from '#lib/ktor-svelte/confirm.ts';
    import { toast } from '#lib/ktor-svelte/toasts.ts';
    import { routes } from '#routes';

    const form = formState<TaskInput>({ ...TaskInput.empty(), priority: 'NORMAL' }, { validate: TaskInput.validate });

    const priorityLabels: Record<Priority, () => string> = {
        LOW: m.priorityLow,
        NORMAL: m.priorityNormal,
        HIGH: m.priorityHigh
    };

    async function create(event: SubmitEvent) {
        event.preventDefault();
        const task = await form.submit((draft) => api.tasks.create(draft));
        if (!task) return;
        toast(m.taskCreated({ title: task.title }), { kind: 'success' });
        await goto(routes.tasksId({ id: task.id }));
    }

    async function discard() {
        if (!form.dirty) return goto(routes.board());
        const sure = await confirmed(m.taskDiscardQuestion(), async () => true, { confirm: m.taskDiscard(), danger: true });
        if (sure) await goto(routes.board());
    }
</script>

<h1 class="mb-6 text-3xl font-bold">{m.navNewTask()}</h1>

<form class="grid max-w-xl gap-3" novalidate onsubmit={create}>
    <Field label={m.fieldTitle()} bind:value={form.draft.title} bounds={TaskInput.bounds.title} errors={form.errors.title} />
    <Field
        label={m.fieldDescription()}
        multiline
        rows={4}
        bind:value={form.draft.description}
        bounds={TaskInput.bounds.description}
        errors={form.errors.description}
        hint={m.taskDescriptionHint()}
    />
    <div class="grid gap-3 sm:grid-cols-3">
        <EnumSelect label={m.fieldPriority()} options={Priority} labels={priorityLabels} bind:value={form.draft.priority} />
        <DateInput label={m.fieldDueOn()} bind:value={form.draft.dueOn} errors={form.errors.dueOn} />
        <DateTimeInput label={m.fieldRemindAt()} bind:value={form.draft.remindAt} errors={form.errors.remindAt} />
    </div>
    <div class="flex gap-2">
        <button class="btn btn-primary" type="submit" disabled={form.submitting}>{m.taskCreate()}</button>
        <button class="btn btn-ghost" type="button" onclick={discard}>{m.taskDiscard()}</button>
    </div>
</form>
svelte
<script lang="ts">
    import LocaleSwitch from '#components/LocaleSwitch.svelte';
    import NavigationProgress from '#components/NavigationProgress.svelte';
    import ThemeToggle from '#components/ThemeToggle.svelte';
    import '#lib/ktor-svelte/app.css';
    import { m } from '#i18n';

    let { children } = $props();
</script>

<NavigationProgress label={m.navLoading()} />

<header class="navbar bg-base-100 border-base-300 gap-2 border-b px-4">
    <span class="flex-1 text-lg font-semibold">{m.appTitle()}</span>
    <ThemeToggle class="w-36" label={m.settingsTheme()} />
    <LocaleSwitch class="w-28" label={m.settingsLanguage()} />
</header>

<main class="mx-auto my-8 max-w-4xl px-4">
    {@render children()}
</main>
  • The JsonSchema bounds on the DTO reach the inputs through bounds, so the browser knows the title is required and at most 120 characters. See Validation.
  • form.submit runs validate first and sends nothing while a field is invalid. When the server still answers 422, its messages land in form.errors and show under the fields.
  • form.submit resolves to undefined when the call failed, and with toasts() on any other failure shows as a toast by itself, so create only handles success.

Guide for coding assistants ​

svelteSync also writes src/lib/ktor-svelte/AGENTS.md, a short guide for coding assistants such as Claude Code, Cursor or Copilot. It tells them what they otherwise get wrong in a project like this:

  • which files are generated and must not be edited, and which Gradle setting or Kotlin route to change instead
  • that the backend is called through the typed client from #api, with apiWith(event) in load functions, never through a hand-written fetch
  • the libraries you turned on and how to use them: icons, messages, themes, toasts
  • your pages by their typed route name, when routes() is on
  • the Gradle commands to run

It describes your project, not ktor-svelte in general: a project without i18n gets no word about messages. Like every generated file it is kept current by svelteSync and checked by svelteVerifySync.

Assistants that read nested AGENTS.md files find it when they work in the frontend. To make sure, link it from the file your assistant reads at the project root, such as AGENTS.md or CLAUDE.md:

md
Read `frontend/src/lib/ktor-svelte/AGENTS.md` before changing anything.

Projects created by the setup script have that AGENTS.md already. ktor-svelte never edits a root AGENTS.md or CLAUDE.md of yours.

Lint rules ​

Next to the generated files, svelteSync writes src/lib/ktor-svelte/eslint.js, a small ESLint plugin with rules for mistakes that are easy to make in a ktor-svelte app. They show up in the editor while you type:

RuleWhat it flags
ktor-svelte/no-string-page-linksAn href, goto or redirect that leads to one of your pages as a string, when typed routes are on
ktor-svelte/fetch-in-loadAn API call inside a load function that goes through neither apiWith(event) nor { fetch }, which SvelteKit reports at runtime as window_fetch_in_load
ktor-svelte/no-error-body-messageReading error.body.message from a caught error without narrowing it with isApiError first, where errorMessage is the safe choice

A project made by the setup script has them wired in. In an existing project, add two lines to eslint.config.js:

js
import ktorSvelte from './src/lib/ktor-svelte/eslint.js';

export default [
    ...ktorSvelte.configs.recommended
];

All three are warnings. To turn one off or make it an error, set it like any other rule:

js
import ktorSvelte from './src/lib/ktor-svelte/eslint.js';

export default [
    ...ktorSvelte.configs.recommended,
    { rules: { 'ktor-svelte/fetch-in-load': 'error' } }
];

The page list inside the file follows your routes, so the first rule stays current the same way routes.ts does. For a one-off check across the whole project, and to rewrite string links automatically, use svelteVerifyRoutes.

Use cases ​

Good to know ​

The components are a starting point

The generated files are rewritten by every svelteSync, so do not edit them. For a different look, write your own component on the same helper. The generated ones are short enough to copy as a start: put the copy in your own folder, such as src/lib/components, and change its relative imports to the aliases, such as #theme or #components/Field.svelte.

They need the generated client

The components import from #api, so the server needs generateTs = true.

Without DaisyUI

The components use plain class names, such as ktor-svelte-field-input, with a minimal style of their own. Toasts and the confirm dialog work too: toasts bring their own small style, and confirmed uses the browser's confirm.

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