svelte-common-hooks

A collection of Svelte custom hooks that I commonly use across projects. Documentation

🛠️ Required Dependencies

This package only run for sveltekit projects, it requires the following dependencies to be installed in your project:

• svelte version 5 or latest
• @sveltejs/kit latest version
• zod/v4

📦 Installation

We have to install zod first

bun add zod

Then we can install this package by executing following command

bun add svelte-common-hooks
# or
npm install svelte-common-hooks
# or
pnpm add svelte-common-hooks
# or
yarn add svelte-common-hooks

📚 Available Hooks

• createDataTable
• createModalState
• createFormState

🚀 Usage

createDataTable

• Source

This is a custom hook for creating data table utilities, it is used to create a data table with pagination, search, and sorting. data fetching can be configured via Mode, it can be done in client Mode, server Mode, or manually make a logic for data fetching via manual Mode.

Client Mode Example:

In client mode, you should define your own function to search data, filter and sorting

• Source

+page.svelte

<script lang="ts">
	import { createDataTable } from 'svelte-common-hooks';

	let { data } = $props();

	/**
	 * Here we initialize the data table with `client` mode, we will manually handle the data fetching.
	 * All of the processing such as filtering, searching, sorting, and pagination will be done client side.
	 * The data is `SSR` ed
	 */
	const dataTable = createDataTable({
		/**
		 * The mode of the data table.
		 */
		mode: 'client',
		/**
		 * The data that will be processed
		 */
		initial: data.users,
		/**
		 * Pass your own function for handle data searching
		 */
		searchWith(item, query) {
			return item.name.toLowerCase().includes(query.toLowerCase());
		},
		/**
		 * You can use your own logic and pass the function for handle data filtering.
		 * This library handle data filtering by doing `Array.filter()` function,
		 * so your function must return `boolean`
		 */
		filters: {
			isAdult: (item, args: boolean | undefined) =>
				typeof args === 'undefined' ? true : item.age >= 18 === args
		},
		/**
		 * You can use your own logic and pass the function for handle data sorting.
		 * This library handle data sorting by doing `Array.sort()` function,
		 * so your function must return `number`
		 */
		sorts: {
			createdAt: (a, b, dir) =>
				dir === 'asc'
					? a.createdAt.getTime() - b.createdAt.getTime()
					: b.createdAt.getTime() - a.createdAt.getTime()
		}
	}).hydrate(() => data.users); // hydrate the data in case the page is invalidated, or you could wrap the dataTable inside `$derived` block
</script>

+page.server.ts

import type { PageServerLoad } from './$types.js';
// mock database query
import { getAllUser } from '../(data)/users.js';

export const load: PageServerLoad = async () => {
	return {
		users: getAllUser()
	};
};

Server Mode Example:

• Source

+page.svelte

<script lang="ts">
	import { page } from '$app/state';
	import { createDataTable, type QueryResult } from 'svelte-common-hooks';
	// see pagination-schema.ts for more info
	import { setPaginationConfig } from '../(schema)/pagination-schema.js';
	import type { User } from '../(data)/users.js';

	const fetchUser = async (url: URL): Promise<QueryResult<User>> => {
		try {
			url ??= new URL($state.snapshot(page.url));
			const response = await fetch(url);
			const data = await response.json();
			if (!response.ok) throw new Error(data);
			if (typeof data === 'object' && 'users' in data && 'totalItems' in data) {
				return { result: data.users, totalItems: data.totalItems };
			}
			return {
				result: [],
				totalItems: 0
			};
		} catch (error) {
			console.error('failed to fetch user', error);
			return {
				result: [],
				totalItems: 0
			};
		}
	};

	/**
	 * Initialize the data table with `server` mode,
	 * we pass the filters and sorts that we want to use,
	 * and the `queryFn` function that will be used to fetch the data.
	 * this mode is not `SSR` able since `$effect` block only runs on client
	 */
	const dataTable = createDataTable({
		mode: 'server',
		/**
		 * we pass the placeholder for the filter,
		 * it is helping us by providing strong typing to do `filterBy` later
		 */
		filters: {
			isAdult: undefined as boolean | undefined
		},
		/**
		 * we pass the placeholder for the sort,
		 * it is helping us by providing strong typing to do `sortBy` later
		 */
		sorts: {
			createdAt: 'desc' as 'asc' | 'desc'
		},
		/**
		 * The query function, this is where the data is fetched from the server.
		 * Make sure to type the return type so that the data table can infer it.
		 * Make sure to read the config from `dataTable.getConfig()` method,
		 * so that it will trigger side effect when the state changes
		 */
		queryFn: async (): Promise<QueryResult<User>> => {
			// if you want this function to rerun, read the config from `dataTable.getConfig()` method
			const config = dataTable.getConfig();
			// we create a new url to send to the server with the config in the searchParam
			const url = setPaginationConfig(new URL(page.url), {
				isAdult: config.filter.isAdult,
				page: config.page,
				search: config.search,
				sort: config.sort.current && config.sort.dir ? config.sort.dir : null,
				limit: config.limit
			});
			// finally, we fetch the data from the server with the updated config
			return await fetchUser(url);
		}
	});
</script>

+server.ts

import type { RequestHandler } from './$types.js';
// see pagination-schema.ts for more info
import { getPaginationConfig } from '../(schema)/pagination-schema.js';
// mock database qery
import { getUser } from '../(data)/users.js';
import { json } from '@sveltejs/kit';

export const GET: RequestHandler = (event) => {
	const config = getPaginationConfig(event.url.searchParams);
	const { users, totalItems } = getUser(config);
	return json({
		users,
		totalItems
	});
};

Manual Mode Example:

• Source

+page.svelte

<script lang="ts">
	import { createDataTable } from '$lib/index.svelte';
	import { page } from '$app/state';
	import { goto } from '$app/navigation';
	// utils for transforming value from page.url.searchParams
	import { stringToBoolean, stringToEnum, stringToNumber } from '../(utils)/utils.js';
	// see pagination-schema.ts for more info
	import { setPaginationConfig } from '../(schema)/pagination-schema.js';
	let { data } = $props();

	/**
	 * Here we initialize the data table with `manual` mode, we will manually handle the data fetching.
	 * we put all of the state like pagination, search, filters, and sorts from the url search params.
	 * Then we use `goto` from sveltekit to force the `load` function to rerun,
	 * and returning the updated data with the config in the `searchParams`.
	 * since we working with the `load` function, this will be `SSR`ed.
	 */
	const dataTable = createDataTable({
		/**
		 * we use `manual` mode, this mode will not do the filter, pagination, search and sort in the client side,
		 * It is encouraging you to move it to the server instead inside `load` function and store the state in the search params.
		 */
		mode: 'manual',
		/**
		 * we pass the paginated/sliced data here
		 */
		initial: data.users,
		/**
		 * we pass the unpaginated/unsliced data so then we know is the data have another page
		 * see how i implemented it in +page.server.ts
		 */
		totalItems: data.totalItems,
		/**
		 * we pass the current page number that we got from url search params,
		 * we do this so that when the user refresh on the url that has page in the search params,
		 * the data table will also be on the same page
		 */
		page: stringToNumber(page.url.searchParams.get('page'), 1),
		/**
		 * we pass the search query that we got from url search params,
		 * we do this so that when the user refresh on the url that has search in the search params,
		 * the data table will also be on the same search query
		 */
		search: page.url.searchParams.get('search') ?? '',
		/**
		 * we pass the filters that we got from url search params,
		 * we do this so that when the user refresh on the url that has filter in the search params,
		 * the data table will also be on the same filter.
		 *
		 * In `manual` mode, the filter object accept Record<string, unknown> type.
		 * It is helping us by providing strong typing to do `filterBy` later
		 */
		filters: {
			isAdult: stringToBoolean(page.url.searchParams.get('isAdult'), undefined)
		},
		/**
		 * we pass the sorts that we got from url search params,
		 * we do this so that when the user refresh on the url that has sort in the search params,
		 * the data table will also be on the same sort.
		 *
		 * In `manual` mode, the sort object accept Record<string, unknown> type.
		 * It is helping us by providing strong typing to do `sortBy` later
		 */
		sorts: {
			createdAt: stringToEnum(page.url.searchParams.get('sort'), ['asc', 'desc'] as const, 'desc')
		},
		/**
		 * In `manual` mode, we get our data with `processWith` function.
		 * We get the state from the dataTable and store it in the url search params
		 * so that our load function can read them and return the updated data
		 */
		processWith: async () => {
			// get the snapshotted config to send to the server
			const config = dataTable.getConfig();
			// create a new url to send to the server with the config in the searchParam
			const url = setPaginationConfig(new URL($state.snapshot(page.url)), {
				isAdult: config.filter.isAdult,
				page: config.page,
				search: config.search,
				sort: config.sort.current && config.sort.dir ? config.sort.dir : null,
				limit: config.limit
			});

			// here we force the `load` function to rerun and sending the updated config in the url object
			await goto(url, {
				// keep the focus in case the user is typing on the search bar
				keepFocus: true,
				// invalidate the `users:manual` load function so that it will rerun
				invalidate: ['users:manual'],
				// prevent the page from scrolling to the top
				noScroll: true
			});

			// we then finally can updated the data and totalItems returning from the `load` function here
			dataTable.updateDataAndTotalItems(data.users, data.totalItems);
		}
	}).effect(
		() => data,
		(instance) => {
			instance.updateDataAndTotalItems(data.users, data.totalItems);
		}
	);
</script>

+page.server.ts

import type { PageServerLoad } from './$types.js';
import { getUser } from '../(data)/users.js';
import { getPaginationConfig } from '../(schema)/pagination-schema.js';

export const load: PageServerLoad = async ({ url, depends }) => {
	depends('users:manual');
	const config = getPaginationConfig(url.searchParams);
	const { users, totalItems } = getUser(config);
	return {
		users,
		totalItems
	};
};

createFormState

• Source

This hooks relies on zod/v4 for validation, so make sure you already installed zod/v4

this hook is used to create a form state, it will validate the form state on input and blur.

<script lang="ts">
	import { createAttribute, createFormState } from 'svelte-common-hooks';
	import type { HTMLInputAttributes } from 'svelte/elements';
	import { z } from 'zod/v4';

	/**
	 * here we create a form state, the form state will validate the form on input and blur
	 * the form state will return an object that contains the value, attribute, result, addErrors, setValue, validate, validateAll
	 * you might also wrap it in a $derived() runes if the initial value is dynamic
	 */
	const formState = createFormState({
		/**
		 * The schema thats use to validate the form.
		 * the schema is required
		 */
		schema: z.object({
			name: z.string().min(1),
			email: z.email(),
			age: z.coerce.number().min(18)
		}),
		/**
		 * The initial value of the form (optional).
		 */
		initial: {
			name: 'John Doe',
			email: '[email protected]',
			age: 18,
			customProperty: 'the property that is not exist in the schema is allowed but ignored'
		},
		/**
		 * Optionally append more attribute to the form field.
		 */
		attribute: {
			email: createAttribute<HTMLInputAttributes>({
				type: 'email',
				required: true
			}),
			age: createAttribute<HTMLInputAttributes>({
				type: 'number',
				required: true,
				min: 18
			})
		}
	});

	function handleSubmit(event: SubmitEvent) {
		event.preventDefault();
		const result = formState.validateAll();
		if (!result.success) {
			return alert('Invalid');
		}
		console.log(result.data);
	}
</script>

<form action="" method="post" onsubmit={handleSubmit}>
	<div>
		<label for="name">Name</label>
		<input bind:value={formState.value.name} {...formState.attribute.name} />
		{#if formState.result.name.errors.length}
			{#each formState.result.name.errors as error}
				<span>{error}</span>
			{/each}
		{/if}
	</div>
	<div>
		<label for="email">Email</label>
		<input bind:value={formState.value.email} {...formState.attribute.email} />
		{#if formState.result.email.errors.length}
			{#each formState.result.email.errors as error}
				<span>{error}</span>
			{/each}
		{/if}
	</div>
	<div>
		<label for="age">Age</label>
		<input bind:value={formState.value.age} {...formState.attribute.age} />
		{#if formState.result.age.errors.length}
			{#each formState.result.age.errors as error}
				<span>{error}</span>
			{/each}
		{/if}
	</div>
</form>

createModalState

• Source

• Creates a state manager for multiple modals by pushing state on the page.

• It would close the modal with navigate back gestures on mobile.

• It will return an object that contains the list, open, close

<script lang="ts">
	import { createModalState } from 'svelte-common-hooks';
	import DialogComponent from './DialogComponent.svelte';
	const modals = createModalState('example');
	let selectedNumber = $state<number>();
</script>

// DialogComponent.svelte
<button onclick={() => modals.open('example', () => (selectedNumber = 2))}>Open Modal 2</button>
{#if modals.list.example}
	<div>
		<h1>Modal 2</h1>
		<button onclick={() => modals.close('example')}>Close</button>
		<!-- or -->
		<button onclick={() => (modals.list.example = false)}>Close</button>
	</div>
{/if}

• We could also bind the state inside the list since the list it self is a state.
• This is how i usually use it with shadcn/svelte dialog

+page.svelte

<script lang="ts">
	import { createModalState } from '$lib/index.svelte';
	import DialogComponent from './DialogComponent.svelte';
	const modals = createModalState('delete');
	let selectedId = $state<number>();
</script>

<DialogComponent bind:open={modals.list.delete} {selectedId} />
<button onclick={() => modals.open('delete', () => (selectedId = 1))}>Delete</button>

DialogComponent.svelte

<script lang="ts">
	let { open = $bindable(false), selectedId }: { open?: boolean; selectedId?: number } = $props();
</script>

<Dialog.Root bind:open>
	<Dialog.Content>
		<Dialog.Header>
			<Dialog.Title>Are you sure absolutely sure?</Dialog.Title>
			<Dialog.Description>
				This action cannot be undone. This will permanently delete your account and remove your data
				from our servers.
			</Dialog.Description>
		</Dialog.Header>
	</Dialog.Content>
</Dialog.Root>

📝 License

Free for personal and non-commercial use. Commercial use requires a separate commercial license. See LICENSE for details.

For commercial licensing inquiries, contact: [[email protected]]