Skip to content

kspace-trk/admin-ui-components

BranchesTags

Repository files navigation

Admin UI Components for Nuxt

管理画面・CMS向けのNuxt UIコンポーネントライブラリです。

Quick Setup

  1. 必要な依存関係をインストール:
npm install kspace-trk/admin-ui-components
  1. nuxt.config.tsにモジュールを追加:
export default defineNuxtConfig({
  modules: [
    '@kspace-trk/admin-ui-components'
  ]
})

全コンポーネントはKSプレフィックス付きでグローバル登録されます。

コンポーネント一覧

カテゴリ コンポーネント 概要
Buttons MainButton 送信・キャンセルボタン
Forms InputField テキスト入力
TextareaField テキストエリア
SelectField セレクトボックス
Checkbox チェックボックス
ToggleSwitch トグルスイッチ
SearchField 検索フィールド
FileUpload ファイルアップロード
Headers TopHeader トップナビゲーション
SideHeader サイドナビゲーション
Layouts DashboardContainer ダッシュボードレイアウト
Display Badge ステータスバッジ
DataTable データテーブル
Panels TextItem テキスト表示パネル
Sections SectionTextWithLine セクション見出し
Navigation Pagination ページネーション
Breadcrumb パンくずリスト
Tabs タブ切り替え
Overlays Modal モーダルダイアログ
Toast トースト通知
DropdownMenu ドロップダウンメニュー
Icons KSIcon Iconifyアイコン表示（@iconify/vueのラッパー）

コンポーネント仕様書

1. ボタンコンポーネント

MainButton

コンポーネント名: KSMainButton ファイルパス: src/runtime/components/buttons/MainButton.vue 機能概要: 送信・キャンセル用のメインボタン。ローディング状態とスピナー表示に対応。

Props:

Prop 型 デフォルト 説明
type 'submit' | 'cancel' 'submit' ボタンタイプ
text string ''（未指定時はtypeに応じて'送信'/'キャンセル'を自動設定） ボタンテキスト
disabled boolean false 無効化状態
loading boolean false ローディング状態
loadingText string '処理中...' ローディング時のテキスト

Events:

Event Payload 説明
click - ボタンクリック時（disabled/loading時は発火しない）

使用例:

<KSMainButton type="submit" text="保存" :loading="isLoading" @click="handleSave" />
<KSMainButton type="cancel" @click="handleCancel" />

2. フォームコンポーネント

InputField

コンポーネント名: KSInputField ファイルパス: src/runtime/components/forms/InputField.vue 機能概要: ラベル付きテキスト入力フィールド。v-model対応。

Props:

Prop 型 デフォルト 説明
label string 必須 フィールドラベル
placeholder string - プレースホルダー
modelValue string - v-model値
type 'text' | 'password' | 'email' | 'number' | 'tel' | 'url' 'text' input要素のtype属性

Events:

Event Payload 説明
update:modelValue string 入力値変更時

使用例:

<KSInputField v-model="form.name" label="名前" placeholder="名前を入力してください" />
<KSInputField v-model="form.email" label="メール" type="email" />

TextareaField

コンポーネント名: KSTextareaField ファイルパス: src/runtime/components/forms/TextareaField.vue 機能概要: ラベル付きテキストエリア。v-model対応、行数指定・読み取り専用モード対応。

Props:

Prop 型 デフォルト 説明
label string 必須 フィールドラベル
placeholder string - プレースホルダー
modelValue string - v-model値
rows number 4 行数
readonly boolean false 読み取り専用モード

Events:

Event Payload 説明
update:modelValue string 入力値変更時

使用例:

<KSTextareaField v-model="form.description" label="説明" :rows="6" />
<KSTextareaField v-model="form.note" label="備考" :readonly="true" />

SelectField

コンポーネント名: KSSelectField ファイルパス: src/runtime/components/forms/SelectField.vue 機能概要: ラベル付きセレクトボックス。v-model対応。

Props:

Prop 型 デフォルト 説明
label string 必須 フィールドラベル
options SelectOption[] 必須 選択肢
modelValue string | number - v-model値
placeholder string - プレースホルダー
disabled boolean - 無効化

型定義:

interface SelectOption {
  label: string
  value: string | number
  disabled?: boolean
}

Events:

Event Payload 説明
update:modelValue string | number 選択値変更時

使用例:

<KSSelectField
  v-model="form.category"
  label="カテゴリ"
  placeholder="カテゴリを選択"
  :options="[
    { label: 'お知らせ', value: 'news' },
    { label: 'ブログ', value: 'blog' },
    { label: 'イベント', value: 'event', disabled: true },
  ]"
/>

Checkbox

コンポーネント名: KSCheckbox ファイルパス: src/runtime/components/forms/Checkbox.vue 機能概要: チェックボックス。v-model対応。

Props:

Prop 型 デフォルト 説明
label string - ラベル
modelValue boolean - v-model値
disabled boolean - 無効化

Events:

Event Payload 説明
update:modelValue boolean チェック状態変更時

使用例:

<KSCheckbox v-model="form.publish" label="公開する" />
<KSCheckbox v-model="form.featured" label="注目記事に設定" />

ToggleSwitch

コンポーネント名: KSToggleSwitch ファイルパス: src/runtime/components/forms/ToggleSwitch.vue 機能概要: トグルスイッチ。ON/OFF切り替え用。v-model対応。

Props:

Prop 型 デフォルト 説明
label string - ラベル
modelValue boolean - v-model値
disabled boolean - 無効化

Events:

Event Payload 説明
update:modelValue boolean ON/OFF切り替え時

使用例:

<KSToggleSwitch v-model="settings.isPublic" label="公開状態" />
<KSToggleSwitch v-model="settings.notification" label="通知を送信" />

SearchField

コンポーネント名: KSSearchField ファイルパス: src/runtime/components/forms/SearchField.vue 機能概要: 検索アイコン・クリアボタン付き検索フィールド。v-model対応。

Props:

Prop 型 デフォルト 説明
placeholder string '検索...' プレースホルダー
modelValue string - v-model値

Events:

Event Payload 説明
update:modelValue string 入力値変更時
search string Enterキー押下時またはクリアボタンクリック時

使用例:

<KSSearchField v-model="query" placeholder="記事を検索..." @search="handleSearch" />

FileUpload

コンポーネント名: KSFileUpload ファイルパス: src/runtime/components/forms/FileUpload.vue 機能概要: ドラッグ&ドロップ対応のファイルアップロードエリア。

Props:

Prop 型 デフォルト 説明
label string - ラベル
accept string - 受け入れるファイルタイプ（例: image/*）
multiple boolean false 複数ファイル選択
disabled boolean false 無効化
maxSize number - 最大ファイルサイズ（バイト）

Events:

Event Payload 説明
change File[] ファイル選択時
error string エラー発生時（サイズ超過等）

使用例:

<KSFileUpload
  label="サムネイル画像"
  accept="image/*"
  :max-size="5242880"
  @change="handleFiles"
  @error="handleError"
/>

3. ヘッダーコンポーネント

TopHeader

コンポーネント名: KSTopHeader ファイルパス: src/runtime/components/headers/TopHeader.vue 機能概要: ページタイトル表示用の固定トップヘッダー。

Props:

Prop 型 デフォルト 説明
title string 必須 ページタイトル
showHamburger boolean - ハンバーガーメニュー表示

Events:

Event Payload 説明
toggleMenu - ハンバーガーメニュークリック時

使用例:

<KSTopHeader title="ユーザー管理" />

SideHeader

コンポーネント名: KSSideHeader ファイルパス: src/runtime/components/headers/SideHeader.vue 機能概要: サイドナビゲーション。レスポンシブ対応（モバイル時はハンバーガーメニュー）。

Props:

Prop 型 デフォルト 説明
logoText string 必須 ロゴテキスト
menuItems SideHeaderMenuItem[] 必須 メニュー項目
menuSections SideHeaderMenuSection[] - セクション付きメニュー
bottomMenuItem SideHeaderMenuItem - ボトムメニュー項目
currentPath string - 現在のパス（未指定時はuseRoute().pathを使用）
isOpen boolean - メニュー開閉状態（モバイル時のハンバーガーメニュー制御用）

型定義:

interface SideHeaderMenuItem {
  path: string
  label: string
  icon: string
  external?: boolean  // trueの場合、NuxtLinkの代わりに<a target="_blank">で外部リンクとして開く
}

interface SideHeaderMenuSection {
  label: string
  items: SideHeaderMenuItem[]
  menuActions?: DropdownMenuItem[]  // セクション見出し横の3点リーダーメニュー
}

Events:

Event Payload 説明
menuItemClick string, Event? メニュー項目クリック時
closeMenu - メニュー閉じる時
sectionActionSelect string, DropdownMenuItem セクションの3点リーダーメニュー選択時（第1引数はセクションラベル）

使用例:

<KSSideHeader
  logo-text="管理画面"
  :menu-items="[
    { path: '/dashboard', label: 'ダッシュボード', icon: 'mdi:view-dashboard' },
    { path: 'https://example.com/docs', label: 'ドキュメント', icon: 'mdi:open-in-new', external: true },
  ]"
  :menu-sections="[
    {
      label: 'コンテンツ',
      items: [
        { path: '/articles', label: '記事一覧', icon: 'mdi:file-document' },
      ],
      menuActions: [
        { key: 'add', label: '追加', icon: 'mdi:plus' },
        { key: 'refresh', label: '更新', icon: 'mdi:refresh' },
      ],
    },
  ]"
  :current-path="$route.path"
  :is-open="isMenuOpen"
  @menu-item-click="handleMenuClick"
  @close-menu="isMenuOpen = false"
  @section-action-select="handleSectionAction"
/>

4. レイアウトコンポーネント

DashboardContainer

コンポーネント名: KSDashboardContainer ファイルパス: src/runtime/components/layouts/DashboardContainer.vue 機能概要: SideHeaderとTopHeaderを統合したダッシュボードレイアウト。

Props:

Prop 型 デフォルト 説明
sideHeaderProps SideHeaderProps 必須 SideHeaderのprops
topHeaderProps TopHeaderProps 必須 TopHeaderのprops（showHamburgerは内部で常にtrueに設定される）

Events:

Event Payload 説明
menuItemClick string, Event? SideHeaderのメニュークリックを中継
closeMenu - メニュー閉じる時
sectionActionSelect string, DropdownMenuItem セクションの3点リーダーメニュー選択時（第1引数はセクションラベル）

Slots:

Slot 説明
default メインコンテンツ領域

使用例:

<KSDashboardContainer
  :side-header-props="{ logoText: '管理画面', menuItems, menuSections }"
  :top-header-props="{ title: 'ダッシュボード' }"
  @menu-item-click="handleMenuClick"
  @section-action-select="handleSectionAction"
>
  <div>ページ内容</div>
</KSDashboardContainer>

5. データ表示コンポーネント

Badge

コンポーネント名: KSBadge ファイルパス: src/runtime/components/display/Badge.vue 機能概要: ステータスや分類を表すバッジ。5種のバリアント対応。

Props:

Prop 型 デフォルト 説明
text string 必須 表示テキスト
variant 'default' | 'success' | 'warning' | 'danger' | 'info' 'default' バリアント

使用例:

<KSBadge text="公開済み" variant="success" />
<KSBadge text="下書き" variant="warning" />
<KSBadge text="エラー" variant="danger" />

DataTable

コンポーネント名: KSDataTable ファイルパス: src/runtime/components/display/DataTable.vue 機能概要: データ一覧表示テーブル。ソート、ローディング状態、セルのslotカスタマイズ、ドラッグ&ドロップによる行の並び替えに対応。

Props:

Prop 型 デフォルト 説明
columns DataTableColumn[] 必須 カラム定義
rows Record<string, unknown>[] 必須 行データ
loading boolean false ローディング状態
emptyMessage string 'データがありません' データなし時のメッセージ
sortKey string - ソート中のカラムキー
sortOrder 'asc' | 'desc' 'asc' ソート方向
clickable boolean true 行クリックを有効にする（cursor: pointer とホバー効果）
draggable boolean false ドラッグ並び替えを有効にする
rowKey string 'id' 各行を識別するキー（ドラッグ後の順序追跡用）

型定義:

interface DataTableColumn {
  key: string
  label: string
  width?: string
  align?: 'left' | 'center' | 'right'
  sortable?: boolean
}

Events:

Event Payload 説明
sort string ソート可能カラムのヘッダークリック時
rowClick Record<string, unknown>, number 行クリック時（行データとインデックス）
reorder { oldIndex: number, newIndex: number } ドラッグによる行の並び替え完了時

Slots:

Slot Props 説明
cell-{key} { row, value, index } 各カラムのセルをカスタマイズ

使用例:

<KSDataTable
  :columns="[
    { key: 'title', label: 'タイトル', sortable: true },
    { key: 'status', label: 'ステータス', width: '120px', align: 'center' },
    { key: 'date', label: '更新日', width: '120px', sortable: true },
  ]"
  :rows="articles"
  :sort-key="sortKey"
  :sort-order="sortOrder"
  @sort="handleSort"
  @row-click="handleRowClick"
>
  <!-- ステータスカラムをBadgeでカスタマイズ -->
  <template #cell-status="{ value }">
    <KSBadge :text="statusLabel(value)" :variant="statusVariant(value)" />
  </template>
</KSDataTable>

ドラッグ並び替えの使用例:

<KSDataTable
  :columns="columns"
  :rows="items"
  :draggable="true"
  row-key="id"
  @reorder="handleReorder"
>
  <!-- 既存のslots -->
</KSDataTable>

<script setup>
const handleReorder = ({ oldIndex, newIndex }) => {
  const item = items.value.splice(oldIndex, 1)[0]
  items.value.splice(newIndex, 0, item)
}
</script>

6. パネルコンポーネント

TextItem

コンポーネント名: KSTextItem ファイルパス: src/runtime/components/panels/TextItem.vue 機能概要: テキスト表示パネル。行数制限、クローズボタン対応。

Props:

Prop 型 デフォルト 説明
text string 必須 表示テキスト
showCloseIcon boolean false クローズアイコン表示
maxLines number 1 最大行数

Events:

Event Payload 説明
close - クローズボタンクリック時

使用例:

<KSTextItem text="表示テキスト" :show-close-icon="true" :max-lines="3" @close="handleClose" />

7. セクションコンポーネント

SectionTextWithLine

コンポーネント名: KSSectionTextWithLine ファイルパス: src/runtime/components/sections/SectionTextWithLine.vue 機能概要: 左側にラインが付いたセクション見出し。

Props:

Prop 型 デフォルト 説明
text string 必須 見出しテキスト

使用例:

<KSSectionTextWithLine text="基本情報" />

8. ナビゲーションコンポーネント

Pagination

コンポーネント名: KSPagination ファイルパス: src/runtime/components/navigation/Pagination.vue 機能概要: ページネーション。v-model対応。

Props:

Prop 型 デフォルト 説明
currentPage number 必須 現在のページ（1始まり）
totalPages number 必須 総ページ数
siblingCount number 1 現在ページの前後に表示するページ数

Events:

Event Payload 説明
update:currentPage number ページ変更時

使用例:

<KSPagination v-model:current-page="page" :total-pages="20" />

Breadcrumb

コンポーネント名: KSBreadcrumb ファイルパス: src/runtime/components/navigation/Breadcrumb.vue 機能概要: パンくずリスト。

Props:

Prop 型 デフォルト 説明
items BreadcrumbItem[] 必須 パンくずアイテム

型定義:

interface BreadcrumbItem {
  label: string
  to?: string  // リンク先（未指定または最後のアイテムの場合はテキストのみ表示）
}

Events:

Event Payload 説明
navigate BreadcrumbItem, number リンククリック時（最後のアイテムでは発火しない）

使用例:

<KSBreadcrumb
  :items="[
    { label: 'ダッシュボード', to: '/dashboard' },
    { label: 'コンテンツ管理', to: '/contents' },
    { label: '記事編集' },
  ]"
  @navigate="handleNavigate"
/>

Tabs

コンポーネント名: KSTabs ファイルパス: src/runtime/components/navigation/Tabs.vue 機能概要: タブ切り替え。名前付きslotでコンテンツを表示。v-model対応。

Props:

Prop 型 デフォルト 説明
tabs TabItem[] 必須 タブ項目
modelValue string 必須 アクティブなタブのキー

型定義:

interface TabItem {
  key: string
  label: string
  disabled?: boolean
}

Events:

Event Payload 説明
update:modelValue string タブ切り替え時

Slots:

Slot 説明
{key} 各タブのコンテンツ（TabItemのkeyが名前）

使用例:

<KSTabs
  v-model="activeTab"
  :tabs="[
    { key: 'basic', label: '基本情報' },
    { key: 'seo', label: 'SEO設定' },
    { key: 'history', label: '変更履歴', disabled: true },
  ]"
>
  <template #basic>
    <p>基本情報の内容</p>
  </template>
  <template #seo>
    <p>SEO設定の内容</p>
  </template>
</KSTabs>

9. オーバーレイコンポーネント

Modal

コンポーネント名: KSModal ファイルパス: src/runtime/components/overlays/Modal.vue 機能概要: モーダルダイアログ。Teleportでbody直下にレンダリング。Escキー・オーバーレイクリックで閉じる。

Props:

Prop 型 デフォルト 説明
open boolean 必須 表示状態
title string - タイトル
width string '480px' モーダルの最大幅（max-widthとして適用）
closeOnOverlay boolean true 背景クリックで閉じるか

Events:

Event Payload 説明
close - モーダルを閉じる時

Slots:

Slot 説明
default 本文コンテンツ
header ヘッダーカスタマイズ
footer フッター（ボタン配置用）

使用例:

<KSMainButton text="削除" @click="showConfirm = true" />

<KSModal :open="showConfirm" title="削除の確認" width="400px" @close="showConfirm = false">
  <p>この記事を削除してよろしいですか？</p>
  <template #footer>
    <KSMainButton type="cancel" text="キャンセル" @click="showConfirm = false" />
    <KSMainButton type="submit" text="削除する" @click="handleDelete" />
  </template>
</KSModal>

Toast

コンポーネント名: KSToast ファイルパス: src/runtime/components/overlays/Toast.vue 機能概要: トースト通知。自動非表示、ホバーでタイマー停止に対応（ホバー解除時はタイマーがリセットされdurationの最初からカウントし直す）。

Props:

Prop 型 デフォルト 説明
visible boolean 必須 表示状態
message string 必須 メッセージ
type 'success' | 'error' | 'warning' | 'info' 'info' タイプ
duration number 3000 自動非表示までの時間（ms）。0で自動非表示しない
position 'top-right' | 'top-center' | 'bottom-right' | 'bottom-center' 'top-right' 表示位置

Events:

Event Payload 説明
close - トーストを閉じる時

使用例:

<KSToast
  :visible="showToast"
  message="記事を保存しました"
  type="success"
  :duration="3000"
  @close="showToast = false"
/>

DropdownMenu

コンポーネント名: KSDropdownMenu ファイルパス: src/runtime/components/overlays/DropdownMenu.vue 機能概要: ドロップダウンメニュー。テーブル行のアクション等に使用。Teleportとposition: fixedによる配置のため、overflow: hiddenな親要素内でも見切れない。スクロール時はトリガーに追従する。同時に複数開かず、別のメニューを開くと既存のものは自動で閉じる。クリック外でも閉じる。

Props:

Prop 型 デフォルト 説明
items DropdownMenuItem[] 必須 メニューアイテム
triggerIcon string 'mdi:dots-vertical' トリガーのIconifyアイコン名

型定義:

interface DropdownMenuItem {
  key: string
  label: string
  icon?: string      // Iconifyアイコン名
  danger?: boolean   // 危険なアクション（赤色表示）
  disabled?: boolean
}

Events:

Event Payload 説明
select DropdownMenuItem アイテム選択時

Slots:

Slot 説明
trigger トリガーボタンのカスタマイズ

使用例:

<KSDropdownMenu
  :items="[
    { key: 'edit', label: '編集', icon: 'mdi:pencil' },
    { key: 'duplicate', label: '複製', icon: 'mdi:content-copy' },
    { key: 'delete', label: '削除', icon: 'mdi:delete', danger: true },
  ]"
  @select="handleAction"
/>

型定義のインポート

コンポーネントが使用する型はライブラリからインポートできます。

import type {
  SideHeaderMenuItem,
  SideHeaderMenuSection,
  SelectOption,
  DataTableColumn,
  BreadcrumbItem,
  TabItem,
  DropdownMenuItem,
} from '@kspace-trk/admin-ui-components/runtime'

アイコンの使用

このライブラリは@iconify/vueのIconコンポーネントをKSIconとしてグローバル登録しています。propsは@iconify/vueのIconと同一です（name/sizeではなくicon/width/heightを使用）。

主なProps:

Prop 型 説明
icon string アイコン名（例: mdi:home）
width string | number アイコンの幅
height string | number アイコンの高さ

widthのみ指定した場合はheightも同じ値になります（逆も同様）。

<KSIcon icon="mdi:home" />
<KSIcon icon="heroicons:user-solid" width="24" height="24" />
<KSIcon icon="mdi:home" width="32" />

利用可能なアイコンはIconifyで検索できます。詳細なpropsは@iconify/vueのドキュメントを参照してください。

技術仕様

依存関係

  • Vue 3
  • Nuxt 3
  • @iconify/vue（アイコン表示）
  • @vueuse/integrations + sortablejs（DataTableのドラッグ並び替え）
  • Sass/SCSS（スタイリング）

デザイントークン

トークン 値 用途
$black-100 #363139 メインテキスト
$black-200 #4B464E サブテキスト
$black-400 #E0E0E0 ボーダー
$white-100 #FFFFFF 背景色
$white-200 #F7F7F7 サブ背景色
$primary-100 #1a1a1a プライマリ（ダーク）
$primary-200 #555555 プライマリ（ミディアム）
$primary-300 #888888 プライマリ（ライト）

ブレークポイント

キー 条件
sm max-width: 400px
md max-width: 768px
lg max-width: 1000px
xl max-width: 1200px

Contribution

Local development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release

About

管理画面開発に適した Vue, Nuxt プロジェクト向けのUIライブラリ

admin-ui-components.k-space.me/

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages