SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillskonsta-ui

konsta-ui

Frontend & websites

View repository

Updated 10-14 05:55

About this skill

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