kuku-ui

Beautiful, accessible Svelte 5 + DaisyUI component library with Tailwind CSS 4.

Installation

npm install kuku-ui

Peer Dependencies

Your project needs these installed:

npm install svelte@^5 @sveltejs/kit@^2 tailwindcss@^4 daisyui@^5 yup@^1
npm install @tailwindcss/vite @tailwindcss/forms @tailwindcss/typography

CSS Setup

Add these lines to your main CSS file (e.g. app.css), after @import "tailwindcss":

@import "tailwindcss";
@source "../node_modules/kuku-ui/src/lib/**/*.svelte";
@import "kuku-ui/base.css";

• @source — tells Tailwind to scan kuku-ui component templates for utility classes
• @import "kuku-ui/base.css" — provides shared theme tokens, base styles, and utility overrides that components depend on

If you use the Form component (which generates grid column classes dynamically), also add:

@source inline("sm:col-span-1 sm:col-span-2 sm:col-span-3 sm:col-span-4 sm:col-span-5 sm:col-span-6 sm:col-span-7 sm:col-span-8 sm:col-span-9 sm:col-span-10 sm:col-span-11 sm:col-span-12");

Quick Start

Import components from kuku-ui:

<script lang="ts">
  import { Button, Modal, toast, Toaster } from 'kuku-ui';
</script>

<Button look="primary" onclick={() => toast.success('Done', 'It works!')}>
  Click me
</Button>

<Toaster />

Components

Buttons

Component	Description
Button	Primary button with variants, loading state, and size options
ButtonIcon	Button with icon + text side-by-side
ButtonLink	Anchor element styled as a button
BtnFloat	Fixed floating action button (bottom-right)
BtnSwap	Toggle button with swap animation (sun/moon theme toggle)

<Button look="primary" size="md" busy={loading} outline>Save</Button>
<Button look="error" size="sm" circle><Cancel /></Button>
<ButtonLink href="/about" look="accent">About</ButtonLink>

Button looks: neutral | primary | secondary | accent | info | success | warning | error | ghost | link

Form System

The Form component renders fields from a schema with built-in Yup validation:

<script lang="ts">
  import { Form, strRequired, emailRequired, type FormSchema } from 'kuku-ui';

  const schema: FormSchema = [
    [
      [
        { name: 'name', type: 'text', label: 'Full Name', col: '6', validate: strRequired },
        { name: 'email', type: 'email', label: 'Email', col: '6', validate: emailRequired }
      ]
    ],
    [
      [
        { name: 'bio', type: 'textarea', label: 'Bio', col: '12' }
      ]
    ]
  ];

  async function handleSubmit(data: { name: string; email: string; bio: string }) {
    await api.save(data);
  }
</script>

<Form id="profile" {schema} onSubmit={handleSubmit} submitText="Save Profile" />

Individual Form Components

Component	Description
Textbox	Text/email/password/number input with autocomplete
Textarea	Multi-line text input
Select	Dropdown with options
Checkbox	Checkbox with label
Radio	Radio button group
SearchList	Async search with single/multi-select and badges
Phone	International phone input with country selector and masking
DateTimePicker	Calendar picker with optional time selection
TimePicker	Time-only picker with minute intervals

<Textbox name="city" label="City" value={city} onChange={(n, v) => city = v} />

<SearchList
  name="tags"
  label="Tags"
  multiple
  onSearch={async (q) => await fetchTags(q)}
  bind:value={selectedTags}
/>

<DateTimePicker
  name="date"
  label="Event Date"
  format="YYYY-MM-DD"
  showTime
  minuteInterval={15}
  bind:value={eventDate}
/>

<Phone name="phone" label="Phone" defaultCountry="US" bind:value={phone} />

Validation Helpers

import {
  strRequired, strOptional,
  emailRequired, emailOptional,
  numRequired,
  validatePwd, validatePhone,
  validateMinLength, validateMaxLength,
  validateNumberRange, validateUrl
} from 'kuku-ui';

Modals

<script lang="ts">
  import { Modal, ModalWithForm } from 'kuku-ui';
  let open = $state(false);
</script>

<!-- Simple modal -->
<Modal bind:open title="Confirm" onOk={handleOk} onCancel={() => open = false}>
  <p>Are you sure?</p>
</Modal>

<!-- Modal with integrated form -->
<ModalWithForm
  {open}
  title="Edit User"
  formID="edit-user"
  formSchema={schema}
  formInitialData={user}
  onSubmit={handleSubmit}
  onCancel={() => open = false}
/>

Sizes: xs | sm | md | lg | xl

Toast Notifications

<script lang="ts">
  import { toast, Toaster } from 'kuku-ui';
</script>

<!-- Place once in your layout -->
<Toaster />

<!-- Trigger from anywhere -->
<button onclick={() => toast.success('Saved', 'Your changes have been saved')}>
  Save
</button>
<button onclick={() => toast.error('Error', 'Something went wrong')}>
  Error
</button>

Methods: toast.info() | toast.success() | toast.warning() | toast.error()

Each accepts (title, message, clearInSeconds?) where clearInSeconds defaults to 7 (use 0 for persistent).

Alert

<Alert type="warning" title="Heads up">
  This action cannot be undone.
</Alert>

Types: info | success | warning | error

ConfirmAction

Wraps any trigger (button, link, toggle) with a confirmation dialog:

<ConfirmAction
  title="Delete Item"
  onConfirm={async () => await deleteItem(id)}
  askForReason
  btnLook="error"
>
  Delete
</ConfirmAction>

Icons

39 SVG icons with optional outline variants:

<script lang="ts">
  import { Calendar, CalendarOutline, Home, Trash, Search } from 'kuku-ui';
  import Icon from 'kuku-ui/svg/Icon.svelte';
</script>

<!-- Direct import -->
<Calendar cls="h-5 w-5" />

<!-- Icon wrapper with outline toggle -->
<Icon icon="home" outline />

Available icons: bar3 calendar cancel checkcircle chevron-left chevron-right error eye folder home info moon pencil pencil-square success sun search trash user warning

DataTable

Server-side paginated table with virtual scrolling, sorting, search, row selection, and mobile card view:

<script lang="ts">
  import { DataTable, type DataTableColumn, type DataTableFetchParams } from 'kuku-ui';

  type User = { id: number; name: string; email: string; role: string };

  const columns: DataTableColumn<User>[] = [
    { key: 'name', label: 'Name', sortable: true },
    { key: 'email', label: 'Email', sortable: true },
    { key: 'role', label: 'Role' }
  ];

  async function fetchUsers({ page, pageSize, search, sortKey, sortDir }: DataTableFetchParams) {
    const res = await fetch(`/api/users?page=${page}&size=${pageSize}&q=${search ?? ''}`);
    return res.json(); // { rows: User[], total: number }
  }
</script>

<DataTable {columns} onFetch={fetchUsers} pageSize={50} cls="h-[600px]" />

Features: virtual scroll for 100K+ rows, column sorting, search with debounce, row selection (selectable), custom cell renderers, mobile-responsive card view, toolbar snippet, empty state snippet.

DataList

Simpler alternative to DataTable — renders arbitrary items via a snippet instead of columns. Same virtual scroll + infinite scroll engine:

<script lang="ts">
  import { DataList, type DataTableFetchParams } from 'kuku-ui';

  type User = { id: number; name: string; email: string };

  async function fetchUsers({ page, pageSize, search }: DataTableFetchParams) {
    const res = await fetch(`/api/users?page=${page}&size=${pageSize}&q=${search ?? ''}`);
    return res.json(); // { rows: User[], total: number }
  }
</script>

<DataList fetcher={fetchUsers} pageSize={50} itemHeight={80} cls="h-[600px]">
  {#snippet itemSnippet(row: User)}
    <div class="flex items-center gap-4 border-b px-4 py-3">
      <div class="font-medium">{row.name}</div>
      <div class="text-sm text-gray-500">{row.email}</div>
    </div>
  {/snippet}
</DataList>

Features: virtual scroll for 100K+ rows, infinite scroll pagination, search with debounce, toolbar snippet, empty state snippet, refresh() method.

DataSelect

Versatile select/combobox with search, single/multi-select, grouped options, async search, and creatable items:

<script lang="ts">
  import { DataSelect, type Option, type OptionGroup } from 'kuku-ui';

  const colors: Option[] = [
    { key: 'red', value: 'Red' },
    { key: 'blue', value: 'Blue' }
  ];

  let selected = $state<Option | undefined>();
  let multiSelected = $state<Option[]>([]);
</script>

<!-- Single select with static options -->
<DataSelect name="color" label="Color" options={colors} bind:value={selected} />

<!-- Multi-select with async search and creatable -->
<DataSelect
  name="tags"
  label="Tags"
  multiple
  creatable
  onSearch={async (q) => await fetchTags(q)}
  bind:value={multiSelected}
/>

Features: client-side filtering, async search with debounce, grouped options (OptionGroup[]), multi-select with badge chips, creatable items, custom item/group/create snippets, clearable, keyboard navigation.

Other Components

Component	Description
Badge	Small decorative label with color and size variants

Portal Action

Teleport DOM elements to a different location:

<script lang="ts">
  import { portal, createPortal } from 'kuku-ui';
</script>

<!-- Target location -->
<div use:createPortal={'my-portal'}></div>

<!-- Content will be moved to target -->
<div use:portal={'my-portal'}>
  This renders at the target location
</div>

Drag and Drop

Custom drag-and-drop with HTML5 Drag API and Pointer Events:

<script lang="ts">
  import { draggable } from 'kuku-ui/drag-and-drop/action-dragable';
  import { droppable } from 'kuku-ui/drag-and-drop/action-dropable';
</script>

<div use:draggable={{ container: 'list-a', dragData: item }}>
  Drag me
</div>

<div use:droppable={{
  container: 'list-b',
  callbacks: {
    onDrop: (data) => handleDrop(data)
  }
}}>
  Drop here
</div>

Styling

kuku-ui uses Tailwind CSS 4 with DaisyUI 5. Components accept cls props for custom classes:

<Button cls="w-full mt-4" look="primary">Full Width</Button>

All form components support a col prop ('1'-'12') for grid layout control and a size prop ('xs' | 'sm' | 'md' | 'lg').

Development

npm run dev          # Dev server
npm run storybook    # Storybook on :6006
npm run check        # Type check
npm run build        # Build library
npm run format       # Prettier

License

MIT