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
- Inspect versions, main CSS file,
tailwind.config.*, postcss.config.*, vite.config.*, index.html viewport meta, whether Ionic is also present.
- Install / upgrade (below). For an existing Tailwind v3 project, migrate Tailwind first (
tailwind-capacitor).
- Wrap the app in
App (or KonstaProvider with Ionic/Framework7).
- Build screens with components: references/components.md.
- 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
npm run build && npx cap sync, run on iOS and Android.
- Inspect
<html>/root: .k-ios or .k-material class present; ios:/material: utilities apply.
- Navbar clears the Dynamic Island; Tabbar clears the home indicator and Android gesture bar (Android 15+ edge-to-edge).
- Toggle dark mode; components and status bar icons switch together.
- 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
1---2name: konsta-ui3description: Builds Capacitor app UI with Konsta UI v5 (Tailwind CSS v4-based iOS and Material components for React 19, Vue 3, Svelte 5) - CSS-first setup (`@import 'tailwindcss'; @import 'konsta/react/theme.css';`), `--color-brand-*` colors in `@theme`, `<App theme="ios|material|parent" safeAreas dark>`, `KonstaProvider` when mixing with Ionic, `ios:`/`material:` variants, `pt-safe`/`no-safe-areas` utilities, `k-md-vibrant`/`k-md-monochrome`, and migrating from Konsta v3/v4 `konstaConfig` in `tailwind.config.js`. Use when installing or upgrading Konsta, components render unstyled, theme or dark mode does not switch, or Navbar/Tabbar overlap system bars. Do not use for Ionic components (ionic-design), plain Tailwind setup without Konsta (tailwind-capacitor), or native safe-area/edge-to-edge config (safe-area-handling).4metadata:5 source: https://skillmd.com/skills/tuyv/konsta-ui6---78# Konsta UI for Capacitor910## When to Use1112TRIGGER when:13- Adding Konsta UI to a Capacitor app or choosing it over Ionic14- Upgrading Konsta v3/v4 (Tailwind v3 `konstaConfig`) to v5 (Tailwind v4)15- Components unstyled, colors ignored, `ios:`/`material:` classes do nothing16- Navbar / Tabbar under the status bar or gesture bar17- Theme should follow platform (`ios` on iPhone, `material` on Android)1819Do not use:20- Ionic Framework components or theming: `ionic-design`21- Tailwind install/config without Konsta: `tailwind-capacitor`22- Android SystemBars / edge-to-edge native config: `safe-area-handling`23- Keyboard overlap in forms: `capacitor-keyboard`2425## Versions (October 2026)2627| Konsta | Tailwind | Frameworks | Config style |28|--------|----------|------------|--------------|29| 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` |30| 4.x | v3 | adds Svelte 5 types | JS: `konstaConfig()` in `tailwind.config.js` |31| 3.x and below | v3 | | JS `konstaConfig()` |3233Check first: `npm ls konsta tailwindcss react vue svelte`. Never mix v5 CSS setup with a `tailwind.config.js` `konstaConfig` wrapper.3435## Workflow36371. **Inspect** versions, main CSS file, `tailwind.config.*`, `postcss.config.*`, `vite.config.*`, `index.html` viewport meta, whether Ionic is also present.382. **Install / upgrade** (below). For an existing Tailwind v3 project, migrate Tailwind first (`tailwind-capacitor`).393. **Wrap the app** in `App` (or `KonstaProvider` with Ionic/Framework7).404. **Build screens** with components: [references/components.md](references/components.md).415. **Verify** (below).4243Only load a reference when its topic is in play.4445## Setup (v5, React shown; Vue/Svelte use `konsta/vue/theme.css` / `konsta/svelte/theme.css`)4647```bash48npm i konsta tailwindcss @tailwindcss/vite49```5051```ts52// vite.config.ts53import tailwindcss from '@tailwindcss/vite';54export default defineConfig({ plugins: [react(), tailwindcss()] });55```5657```css58/* src/index.css */59@import 'tailwindcss';60@import 'konsta/react/theme.css';6162@theme {63 --color-brand-primary: #007aff; /* only --color-brand-* drive component colors */64 --color-brand-red: #ff3b30; /* use with class k-color-brand-red */65}66```6768```tsx69import { Capacitor } from '@capacitor/core';70import { App } from 'konsta/react';7172const theme = Capacitor.getPlatform() === 'android' ? 'material' : 'ios';7374export default function Root() {75 return (76 <App theme={theme} safeAreas>77 {/* pages */}78 </App>79 );80}81```8283```html84<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />85```8687`App` props: `theme` (`'ios' | 'material' | 'parent'`, default `material`), `safeAreas` (default `true`), `dark`, `iosHoverHighlight`, `materialTouchRipple` (global switches added in v5). Only one `App` per app.8889Material Roboto font: add it yourself (Google Fonts link or self-hosted for offline). iOS uses the system font.9091## Migrating v4 -> v59293| v4 | v5 |94|----|----|95| `tailwind.config.js`: `module.exports = konstaConfig({...})` | Delete wrapper; `@import 'konsta/react/theme.css'` in CSS |96| `konstaConfig.colors.primary` | `@theme { --color-brand-primary: ... }` |97| Per-component ripple config | Prefer the global `App materialTouchRipple`; check component types in your installed version |98| `SegmentedButton strong rounded` | Removed; use Segmented theme-specific style props |99| `Link navbar/toolbar/tabbar` props | Removed; context-driven |100| React `forwardRef` usage / `innerRef` patterns | `ref` prop (React 19) |101| Svelte slots | `{#snippet ...}` |102103Then run the Tailwind v4 upgrade (`npx @tailwindcss/upgrade`) if Tailwind itself is still v3; see `tailwind-capacitor`.104105## Traps106107- 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.108- 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`.109- 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.110- Modals/side panels that are not full-screen need `no-safe-areas` (or `no-safe-areas-top` etc.) to avoid extra padding.111- 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`.112113## Verification1141151. `npm run build && npx cap sync`, run on iOS and Android.1162. Inspect `<html>`/root: `.k-ios` or `.k-material` class present; `ios:`/`material:` utilities apply.1173. Navbar clears the Dynamic Island; Tabbar clears the home indicator and Android gesture bar (Android 15+ edge-to-edge).1184. Toggle dark mode; components and status bar icons switch together.1195. Leftover check: `grep -rn "konstaConfig\|konsta/config" .` returns nothing on v5.120121## Error Handling122123| Error / symptom | Cause | Fix |124|-----------------|-------|-----|125| `Cannot find module 'konsta/config'` | v5 removed JS config | Use CSS `@import 'konsta/react/theme.css'` |126| 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 |127| `[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` |128| Brand color ignored | Variable not named `--color-brand-*`, or defined outside `@theme` | Rename inside `@theme` |129| `ios:` classes have no effect | `App`/`KonstaProvider` missing, so no `.k-ios` ancestor | Wrap app |130| React warning about `ref` / `forwardRef` after upgrade | React 18 with Konsta 5 | Upgrade to React 19 or stay on Konsta 4 |131| Double top padding | Konsta `safeAreas` + Ionic or custom `env()` padding | Keep one owner |132133## Resources134135- Konsta UI: https://konstaui.com136- React installation: https://konstaui.com/react/installation137- Safe areas: https://konstaui.com/react/safe-areas138- Colors: https://konstaui.com/react/colors139- Changelog: https://github.com/konstaui/konsta/blob/master/CHANGELOG.md