konsta-ui

Capacitor 向け Konsta UI

使用するタイミング

次の場合に使用します：

• Capacitor アプリに Konsta UI を追加する場合、または Ionic の代わりに Konsta UI を選ぶ場合
• Konsta v3/v4（Tailwind v3 の konstaConfig）から v5（Tailwind v4）にアップグレードする場合
• コンポーネントのスタイルが適用されない、色が反映されない、ios:／material: クラスが機能しない場合
• Navbar／Tabbar がステータスバーまたはジェスチャーバーの下に表示される場合
• テーマをプラットフォームに合わせる場合（iPhone では ios、Android では material）

次の場合は使用しないでください：

• Ionic Framework のコンポーネントまたはテーマ：ionic-design
• Konsta を使わない Tailwind のインストール／設定：tailwind-capacitor
• Android SystemBars／エッジツーエッジのネイティブ設定：safe-area-handling
• フォームでのキーボードの重なり：capacitor-keyboard

バージョン（2026年10月）

Konsta	Tailwind	フレームワーク	設定方式
5.x（latest、5.5.0）	v4	React 19（ref をプロパティとして使用）、Vue 3、Svelte 5（runes、snippets）	CSS：@import 'konsta/<fw>/theme.css' ＋ @theme
4.x	v3	Svelte 5 の型を追加	JS：tailwind.config.js の konstaConfig()
3.x 以下	v3		JS konstaConfig()

最初に確認します：npm ls konsta tailwindcss react vue svelte。v5 の CSS 設定と、tailwind.config.js の konstaConfig ラッパーを決して混在させないでください。

ワークフロー

1. 確認：バージョン、メインの CSS ファイル、tailwind.config.*、postcss.config.*、vite.config.*、index.html の viewport メタデータ、Ionic も導入されているかどうかを確認します。
2. インストール／アップグレード（以下を参照）。既存の Tailwind v3 プロジェクトでは、先に Tailwind を移行します（tailwind-capacitor）。
3. アプリを App でラップします（Ionic／Framework7 と併用する場合は KonstaProvider を使用します）。
4. コンポーネントを使って画面を構築します：references/components.md。
5. 検証します（以下を参照）。

該当するトピックを扱う場合にのみ、リファレンスを読み込んでください。

セットアップ（v5、React の例。Vue／Svelte では 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 のプロパティ：theme（'ios' | 'material' | 'parent'、デフォルトは material）、safeAreas（デフォルトは true）、dark、iosHoverHighlight、materialTouchRipple（v5 で追加されたグローバルな切り替え）。アプリ内で App は 1 つだけにしてください。

Material の Roboto フォントは自分で追加してください（Google Fonts のリンク、またはオフライン用にセルフホスト）。iOS ではシステムフォントが使われます。

v4 から v5 への移行

v4	v5
tailwind.config.js：module.exports = konstaConfig({...})	ラッパーを削除し、CSS に @import 'konsta/react/theme.css' を記述
konstaConfig.colors.primary	@theme { --color-brand-primary: ... }
コンポーネントごとのリップル設定	グローバルな App materialTouchRipple を推奨します。インストール済みのバージョンでコンポーネントの型を確認してください
SegmentedButton strong rounded	削除されました。Segmented のテーマ固有のスタイルプロパティを使用してください
Link navbar/toolbar/tabbar プロパティ	削除されました。コンテキストによって制御されます
React の forwardRef の使用／innerRef のパターン	ref プロパティ（React 19）
Svelte のスロット	{#snippet ...}

Tailwind 自体がまだ v3 の場合は、Tailwind v4 のアップグレード（npx @tailwindcss/upgrade）を実行してください。tailwind-capacitor を参照してください。

注意点

• 同じアプリで Ionic を使用する場合は、App ではなく KonstaProvider を使用し、セーフエリアの管理元は Ionic の --ion-safe-area-* または Konsta の safe-areas のどちらか一方にしてください。両方を使わないでください。
• Konsta v5 のダークモードはクラスベースです（CSS に @custom-variant dark (&:where(.dark, .dark *)) を指定します）。<html> に dark を切り替え、App dark を設定し、ネイティブバーを SystemBars.setStyle と合わせてください。
• Konsta のドキュメントでは user-scalable=no, maximum-scale=1 が示されていますが、アクセシビリティのためにズームを許可し、代わりに iOS の入力欄のズームは入力欄を 16px にして防ぐことを推奨します。
• 全画面表示ではないモーダル／サイドパネルでは、余分なパディングを避けるために no-safe-areas（または no-safe-areas-top など）が必要です。
• Konsta は UI のみを提供し、ルーターやページ遷移はありません。React Router／Vue Router／SvelteKit と組み合わせ、Android の戻るボタンは @capacitor/app の backButton で処理してください。

検証

1. npm run build && npx cap sync を実行し、iOS と Android で動作させます。
2. <html>／ルート要素を確認します。.k-ios または .k-material クラスが存在し、ios:／material: ユーティリティが適用されます。
3. ナビゲーションバーが Dynamic Island と重ならず、タブバーがホームインジケーターと Android のジェスチャーバー（Android 15 以降のエッジツーエッジ）と重ならないことを確認します。
4. ダークモードを切り替えます。コンポーネントとステータスバーのアイコンが一緒に切り替わります。
5. 残存箇所を確認します。v5 では grep -rn "konstaConfig\|konsta/config" . の実行結果が空になります。

エラー処理

エラー／症状	原因	対処法
Cannot find module 'konsta/config'	v5 で JavaScript 設定が削除されました	CSS の @import 'konsta/react/theme.css' を使用します
コンポーネントにスタイルが適用されない	テーマ CSS がインポートされていないか、Tailwind のスキャン対象に含まれていません（@tailwindcss/vite／@tailwindcss/postcss がありません）	@import 'tailwindcss' の後にテーマをインポートし、Tailwind プラグインを追加します
[postcss] It looks like you're trying to use tailwindcss directly as a PostCSS plugin	Tailwind v4 で PostCSS プラグインが移動しました	@tailwindcss/postcss または @tailwindcss/vite を使用します
ブランドカラーが反映されない	変数名が --color-brand-* ではないか、@theme の外で定義されています	@theme 内で名前を変更します
ios: クラスが効果を発揮しない	App／KonstaProvider がなく、.k-ios の祖先要素がありません	アプリをラップします
アップグレード後に ref／forwardRef に関する React の警告が表示される	React 18 と Konsta 5 の組み合わせです	React 19 にアップグレードするか、Konsta 4 を使い続けます
上部のパディングが二重になる	Konsta の safeAreas と Ionic またはカスタムの env() パディングが併用されています	管理元を一つにします

リソース

• Konsta UI：https://konstaui.com
• React のインストール：https://konstaui.com/react/installation
• セーフエリア：https://konstaui.com/react/safe-areas
• カラー：https://konstaui.com/react/colors
• 変更履歴：https://github.com/konstaui/konsta/blob/master/CHANGELOG.md