konsta-ui

Konsta UI for Capacitor

When to Use

TRIGGER when:

• Adding Konsta UI to a Capacitor app or choosing it over Ionic
• Upgrading Konsta v3/v4 (Tailwind v3 konstaConfig) to v5 (Tailwind v4)
• Components unstyled, colors ignored, ios:/material: classes do nothing
• Navbar / Tabbar under the status bar or gesture bar
• Theme should follow platform (ios on iPhone, material on Android)

Do not use:

• Ionic Framework components or theming: ionic-design
• Tailwind install/config without Konsta: tailwind-capacitor
• Android SystemBars / edge-to-edge native config: safe-area-handling
• Keyboard overlap in forms: capacitor-keyboard

Versions (October 2026)

Konsta	Tailwind	Frameworks	Config style
5.x (latest, 5.5.0)	v4	React 19 (ref as prop), Vue 3, Svelte 5 (runes, snippets)	CSS: @import 'konsta/<fw>/theme.css' + @theme
4.x	v3	adds Svelte 5 types	JS: konstaConfig() in tailwind.config.js
3.x and below	v3		JS konstaConfig()

Check first: npm ls konsta tailwindcss react vue svelte. Never mix v5 CSS setup with a tailwind.config.js konstaConfig wrapper.

Workflow

1. Inspect versions, main CSS file, tailwind.config.*, postcss.config.*, vite.config.*, index.html viewport meta, whether Ionic is also present.
2. Install / upgrade (below). For an existing Tailwind v3 project, migrate Tailwind first (tailwind-capacitor).
3. Wrap the app in App (or KonstaProvider with Ionic/Framework7).
4. Build screens with components: references/components.md.
5. Verify (below).

Only load a reference when its topic is in play.

Setup (v5, React shown; Vue/Svelte use konsta/vue/theme.css / konsta/svelte/theme.css)

npm i konsta tailwindcss @tailwindcss/vite

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({ plugins: [react(), tailwindcss()] });

/* src/index.css */
@import 'tailwindcss';
@import 'konsta/react/theme.css';

@theme {
  --color-brand-primary: #007aff; /* only --color-brand-* drive component colors */
  --color-brand-red: #ff3b30;     /* use with class k-color-brand-red */
}

import { Capacitor } from '@capacitor/core';
import { App } from 'konsta/react';

const theme = Capacitor.getPlatform() === 'android' ? 'material' : 'ios';

export default function Root() {
  return (
    <App theme={theme} safeAreas>
      {/* pages */}
    </App>
  );
}

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

App props: theme ('ios' | 'material' | 'parent', default material), safeAreas (default true), dark, iosHoverHighlight, materialTouchRipple (global switches added in v5). Only one App per app.

Material Roboto font: add it yourself (Google Fonts link or self-hosted for offline). iOS uses the system font.

Migrating v4 -> v5

v4	v5
tailwind.config.js: module.exports = konstaConfig({...})	Delete wrapper; @import 'konsta/react/theme.css' in CSS
konstaConfig.colors.primary	@theme { --color-brand-primary: ... }
Per-component ripple config	Prefer the global App materialTouchRipple; check component types in your installed version
SegmentedButton strong rounded	Removed; use Segmented theme-specific style props
Link navbar/toolbar/tabbar props	Removed; context-driven
React forwardRef usage / innerRef patterns	ref prop (React 19)
Svelte slots	{#snippet ...}

Then run the Tailwind v4 upgrade (npx @tailwindcss/upgrade) if Tailwind itself is still v3; see tailwind-capacitor.

Traps

• With Ionic in the same app, use KonstaProvider (not App) and pick one owner for safe areas (Ionic's --ion-safe-area-* or Konsta's safe-areas), not both.
• Dark mode in Konsta v5 is class-based (@custom-variant dark (&:where(.dark, .dark *)) in its CSS): toggle dark on <html>, set App dark, and match native bars with SystemBars.setStyle.
• Konsta's own docs show user-scalable=no, maximum-scale=1; prefer allowing zoom for accessibility and fix iOS input zoom with 16px inputs instead.
• Modals/side panels that are not full-screen need no-safe-areas (or no-safe-areas-top etc.) to avoid extra padding.
• Konsta is UI only: no router, no page transitions. Pair with React Router / Vue Router / SvelteKit and handle Android back button with @capacitor/app backButton.

Verification

1. npm run build && npx cap sync, run on iOS and Android.
2. Inspect <html>/root: .k-ios or .k-material class present; ios:/material: utilities apply.
3. Navbar clears the Dynamic Island; Tabbar clears the home indicator and Android gesture bar (Android 15+ edge-to-edge).
4. Toggle dark mode; components and status bar icons switch together.
5. Leftover check: grep -rn "konstaConfig\|konsta/config" . returns nothing on v5.

Error Handling

Error / symptom	Cause	Fix
Cannot find module 'konsta/config'	v5 removed JS config	Use CSS @import 'konsta/react/theme.css'
Components render unstyled	Theme CSS not imported, or Tailwind not scanning (no @tailwindcss/vite / @tailwindcss/postcss)	Import theme after @import 'tailwindcss'; add the Tailwind plugin
[postcss] It looks like you're trying to use tailwindcss directly as a PostCSS plugin	Tailwind v4 PostCSS plugin moved	Use @tailwindcss/postcss or @tailwindcss/vite
Brand color ignored	Variable not named --color-brand-*, or defined outside @theme	Rename inside @theme
ios: classes have no effect	App/KonstaProvider missing, so no .k-ios ancestor	Wrap app
React warning about ref / forwardRef after upgrade	React 18 with Konsta 5	Upgrade to React 19 or stay on Konsta 4
Double top padding	Konsta safeAreas + Ionic or custom env() padding	Keep one owner

Resources

• Konsta UI: https://konstaui.com
• React installation: https://konstaui.com/react/installation
• Safe areas: https://konstaui.com/react/safe-areas
• Colors: https://konstaui.com/react/colors
• Changelog: https://github.com/konstaui/konsta/blob/master/CHANGELOG.md