syncfusion-react-dropdowns

Syncfusion React Dropdowns の実装

AutoComplete

AutoComplete コンポーネントは、入力フィールドへの入力に応じて一致する候補リストを表示し、フィルターされた結果から選択できるようにします。ローカルおよびリモートのデータ、豊富なフィルターオプション、テンプレート、グループ化、仮想化、完全なアクセシビリティに対応しています。

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• パッケージのインストール（@syncfusion/ej2-react-dropdowns）
• CSS のインポートとテーマ設定
• 基本的なコンポーネントのセットアップ（関数コンポーネントとクラスコンポーネント）
• シンプルな文字列配列のバインド
• ポップアップの高さと幅の設定（popupHeight、popupWidth）

データバインディング

📄 参照： references/data-binding.md

• 文字列または数値の配列
• fields マッピング（value、groupBy、iconCss）を使用したオブジェクトの配列
• 複雑なオブジェクト／ネストされたオブジェクトの配列（ドット記法によるフィールドマッピング）
• DataManager を使用したリモートデータ（ODataV4Adaptor、WebApiAdaptor）
• query プロパティを使用したリモートデータのフィルター／選択
• アルファベット順に並べ替える sortOrder

フィルタリング

📄 参照： references/filtering.md

• フィルターの種類：StartsWith、EndsWith、Contains
• suggestionCount – 候補数の上限
• minLength – 検索が開始されるまでの最小文字数
• ignoreCase – 大文字と小文字を区別するフィルタリング
• ignoreAccent – ダイアクリティカルマークを考慮したフィルタリング
• debounceDelay – リクエスト数を減らすためのフィルタリングの遅延
• filtering イベントを使用したカスタムフィルタリング

グループ化

📄 参照： references/grouping.md

• fields.groupBy を使用した項目のグループ化
• 固定グループヘッダーとインラインのグループヘッダー
• groupTemplate を使用したカスタムグループヘッダー

テンプレート

📄 参照： references/templates.md

• itemTemplate – 各リスト項目のカスタマイズ
• groupTemplate – グループヘッダーのカスタマイズ
• headerTemplate – ポップアップの静的ヘッダー
• footerTemplate – ポップアップの静的フッター
• noRecordsTemplate – データが見つからない場合のメッセージ
• actionFailureTemplate – リモートデータの取得に失敗した場合のメッセージ

値のバインディング

📄 参照： references/value-binding.md

• プリミティブ値（文字列、数値）のバインド
• allowObjectBinding を使用したオブジェクトのバインド
• value プロパティを使用した選択値の事前設定

仮想化

📄 参照： references/virtual-scroll.md

• 大規模なデータセット向けの enableVirtualization
• VirtualScroll サービスのインジェクト
• ローカルデータ、リモートデータ、グループ化を使用した仮想スクロール
• query.take() を使用した項目数のカスタマイズ

無効化された項目

📄 参照： references/disabled-items.md

• fields.disabled による項目の無効化
• 動的な無効化を行う disableItem メソッド
• enabled={false} によるコンポーネント全体の無効化

アクセシビリティとローカライズ

📄 参照： references/accessibility-localization.md

• WAI-ARIA のロールと属性
• キーボード操作のショートカット
• RTL 対応（enableRtl）
• L10n によるローカライズ（noRecordsTemplate、actionFailureTemplate のテキスト）
• WCAG 2.2 準拠の概要

スタイル設定とカスタマイズ

📄 参照： references/styling.md

• ラッパー、アイコン、フォーカス、プレースホルダー、選択状態の CSS クラス対象
• フローティングラベルのカスタマイズ
• ポップアップ項目の外観
• カスタムクラスを注入する cssClass プロパティ
• ポップアップのサイズ変更（allowResize）
• 必須項目のアスタリスクのスタイル設定

ハウツー：自動入力、ハイライト、アイコン

📄 参照： references/how-to.md

• autofill – Arrow Down キーを押すと最初に一致した項目を候補として表示
• highlight – 候補リスト内で入力文字をハイライト
• fields.iconCss によるアイコンのサポート

API リファレンス

📄 読む： references/api.md

• すべてのプロパティの型、デフォルト値、説明
• すべてのメソッドのパラメーターと戻り値の型
• すべてのイベントの説明

クイックスタートの例

インストール： サプライチェーンのリスクを低減するため、パッケージのメジャーバージョンを指定してください。

npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-react-inputs@^33.x.x @syncfusion/ej2-base@^33.x.x

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-inputs/styles/tailwind3.css';
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';

const sportsData: string[] = [
  'Badminton', 'Basketball', 'Cricket', 'Football',
  'Golf', 'Hockey', 'Rugby', 'Snooker', 'Tennis'
];

export default function App() {
  return (
    <AutoCompleteComponent
      id="sports-ac"
      dataSource={sportsData}
      placeholder="Find a game"
    />
  );
}

よく使われるパターン

フィールドマッピングを使用したオブジェクトデータソース

const sportsData = [
  { id: 'Game1', game: 'Badminton' },
  { id: 'Game2', game: 'Basketball' },
];
const fields = { value: 'game' };

<AutoCompleteComponent dataSource={sportsData} fields={fields} placeholder="Find a game" />

リモートデータバインディング（セキュリティ優先）

セキュリティ： クライアントコードから任意のサードパーティ URL を直接呼び出さないでください。許可されたエンドポイント、認証、レート制限、レスポンスの検証を適用する、信頼できるサーバー側プロキシを経由して外部 API を呼び出してください。

import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';

// Use a controlled server proxy endpoint here. Do not use public third-party URLs directly.
const customerData = new DataManager({
  adaptor: new ODataV4Adaptor(),
  crossDomain: true,
  url: 'https://your-trusted-proxy.example/api/customers'
});
const query = new Query().from('Customers').select(['ContactName', 'CustomerID']).take(6);
const fields = { value: 'ContactName' };

<AutoCompleteComponent
  dataSource={customerData}
  query={query}
  fields={fields}
  sortOrder="Ascending"
  placeholder="Find a customer" />

カスタムオプションを使用したフィルタリング

<AutoCompleteComponent
  dataSource={sportsData}
  filterType="StartsWith"
  minLength={2}
  suggestionCount={5}
  debounceDelay={300}
  ignoreCase={true}
  placeholder="Type to search"
/>

ref 経由でのメソッドへのアクセス

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns';
import { useRef } from 'react';

export default function App() {
  const acRef = useRef<AutoCompleteComponent>(null);

  return (
    <>
      <AutoCompleteComponent ref={acRef} dataSource={sportsData} placeholder="Find a game" />
      <button onClick={() => acRef.current?.showPopup()}>Open</button>
      <button onClick={() => acRef.current?.clear()}>Clear</button>
    </>
  );
}

ComboBox

ComboBox コンポーネントは、ユーザーが入力して項目を絞り込んだり、定義済みリストから選択したりできるドロップダウン入力を提供します。ローカルおよびリモートのデータバインディング、カスタム値、フィルタリング、グループ化、テンプレート、仮想スクロール、包括的なアクセシビリティに対応しています。

コンポーネントの概要

ComboBox は、入力フィールドと選択リストをつなぐ特化型ドロップダウン入力です。主な特徴は次のとおりです。

• ハイブリッド入力： ユーザーは入力して絞り込むことも、ドロップダウンから選択することもできます
• スマートフィルタリング： デフォルトのフィルターはテキストで検索します。複雑なシナリオ向けにカスタマイズも可能です
• 柔軟なデータ： 文字列、JSON オブジェクト、OData、Web API、DataManager に対応しています
• 豊富な UI： 項目、ヘッダー、フッター、選択値、結果なし状態のテンプレートを利用できます
• パフォーマンス： 仮想スクロールにより、数千件の項目を効率的に処理できます
• グローバル対応： ローカライズ、RTL サポート、ARIA 属性を標準で備えています
• アクセシブル： 完全なキーボード操作とスクリーンリーダーに対応しています

インストール： サプライチェーンのリスクを低減するため、パッケージのメジャーバージョンを指定してください。

npm install @syncfusion/ej2-react-dropdowns@^33.x.x

---

ドキュメントのナビゲーションガイド

タスクに応じて、最初に読むドキュメントを選択してください。

はじめに

📄 読む： references/getting-started.md

次の場合にお読みください：

• 新しいプロジェクトで ComboBox を設定する
• コンポーネントを初めて実装する
• 基本的な使い方（クラスコンポーネントと関数コンポーネント）を理解する
• CSS のインポートとテーマを追加する
• カスタム値を有効にする

データバインディングとソース

📄 読む： references/data-binding.md

次の場合にお読みください：

• ローカルデータ（文字列配列、JSON オブジェクト）をバインドする
• リモート API（OData、Web API、DataManager）に接続する
• オブジェクトのフィールド（text、value、groupBy、iconCss）をマッピングする
• 複雑なデータ変換を処理する
• データソースの設定を理解する

フィルタリングと検索動作

📄 読む： references/filtering-and-search.md

次の場合にお読みください：

• テキストフィルタリングを実装する
• カスタムフィルター関数を作成する
• 検索動作（大文字と小文字の区別、一部一致）を設定する
• 大規模なデータセットのパフォーマンスを最適化する
• 結果がない場合を処理する

グループ化と並べ替え

📄 読む： references/grouping-and-sorting.md

次の場合にお読みください：

• 項目を論理的なグループに整理する
• グループヘッダーの表示をカスタマイズする
• 並べ替え順（昇順／降順）を適用する
• グループ化とフィルタリングを組み合わせる
• 複数階層のグループ化を行う

テンプレートとカスタマイズ

📄 読む： references/templates-and-customization.md

次の場合にお読みください：

• カスタム項目テンプレートを作成する
• リッチコンテンツ（画像、アイコン、説明）を表示する
• ヘッダー／フッターテンプレートを使用する（例：アクションボタン、概要）
• 選択値テンプレートの書式を設定する
• CSS クラスによるスタイル設定とテーマをカスタマイズする

高度な機能

📄 参照： references/advanced-features.md

次のような場合に参照してください：

• 大規模なデータセット（10,000 件以上）での仮想スクロール
• 国際化（i18n）と言語の切り替え
• アラビア語／ヘブライ語向けの RTL（右から左）サポート
• アクセシビリティへの準拠（WCAG 2.1、ARIA 属性）
• 無効状態と複数選択のワークフロー
• キーボードショートカットとフォーカス管理

スタイル設定とテーマ設定

📄 参照： references/styling-and-theming.md

次のような場合に参照してください：

• 組み込みの Syncfusion テーマ（Material、Bootstrap、Tailwind）の適用
• ブランドカラーに合わせた CSS 変数のカスタマイズ
• デザインをカスタマイズするための Theme Studio との連携
• レスポンシブデザインのパターン
• ダークモード／ライトモードのサポート

ポップアップのサイズ変更

📄 参照： references/popup-resizing.md

次のような場合に参照してください：

• ユーザーがドロップダウンのサイズを動的に変更できるようにする
• サイズ変更の設定をセッション間で保存する
• カスタムテンプレートを使って長いコンテンツを処理する
• モバイルで使いやすいドロップダウンのサイズ設定

ハウツーガイド

📄 参照： references/how-to-guide.md

次のような場合に参照してください：

• オートフィル（入力中の自動補完）の実装
• 連動するドロップダウン（国 → 州 → 市）の作成
• リスト項目へのアイコンの表示
• 一般的な実用的実装シナリオ

トラブルシューティング

📄 参照： references/troubleshooting.md

次のような場合に参照してください：

• パフォーマンスの問題（レンダリングの遅延、ラグ）
• データバインディングの問題
• EJ1 ComboBox からの移行
• よくあるエッジケースと回避策
• デバッグのヒントとコミュニティリソース

API リファレンス

📄 参照： references/api.md

次のような場合に参照してください：

• 特定のプロパティ、メソッド、イベント名とその型を調べる
• 各種設定オプションのデフォルト値を確認する
• イベント引数の形式を確認する（ChangeEventArgs、FilteringEventArgs など）
• プログラム制御に利用できるすべてのメソッドを確認する
• インターフェイスモデル（FieldSettingsModel、PopupEventArgs など）を確認する

---

クイックスタートの例

インストールとセットアップ

インストール： サプライチェーンのリスクを軽減するため、パッケージのメジャーバージョンを固定してください。

npm install @syncfusion/ej2-react-dropdowns@^33.x.x

基本的な ComboBox（関数コンポーネント）

import { ComboBoxComponent } from '@syncfusion/ej2-react-dropdowns';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';

export default function App() {
  const sportsList = ['Badminton', 'Cricket', 'Football', 'Golf', 'Tennis'];

  return (
    <ComboBoxComponent 
      id="combobox"
      dataSource={sportsList}
      placeholder="Select a sport"
      allowCustom={true}
    />
  );
}

データバインディングを使用する場合（JSON オブジェクト）

export default function App() {
  const sportsData = [
    { Id: 'game1', Game: 'Badminton', Players: 2 },
    { Id: 'game2', Game: 'Football', Players: 11 },
    { Id: 'game3', Game: 'Cricket', Players: 11 }
  ];

  const fields = { text: 'Game', value: 'Id' };

  return (
    <ComboBoxComponent 
      id="combobox"
      dataSource={sportsData}
      fields={fields}
      placeholder="Select a game"
      change={(e) => console.log('Selected:', e.value)}
    />
  );
}

---

一般的なパターン

パターン 1：ユーザー選択用の絞り込み検索

問題： ユーザーが 500 件以上のリストから項目を探す必要があります。
解決策： 入力を制御しながら絞り込みを使用して、一致する項目のみを表示します。非常に大規模なデータセット（5,000 件以上）の場合は、enableVirtualization と VirtualScroll のインジェクションを組み合わせます。

import { ComboBoxComponent, Inject, VirtualScroll } from '@syncfusion/ej2-react-dropdowns';

const [filterValue, setFilterValue] = useState('');

<ComboBoxComponent 
  dataSource={largeDataset}
  fields={{ text: 'name', value: 'id' }}
  filtering={(e) => filterByName(e, 'name')}
  change={(e) => setFilterValue(e.value)}
  allowFiltering={true}
  enableVirtualization={true}
  popupHeight="200px"
>
  <Inject services={[VirtualScroll]} />
</ComboBoxComponent>

パターン 2：カテゴリのグループ化

問題： 項目を種類別に整理し、わかりやすくする必要があります。
解決策： カテゴリ別にグループ化したデータを使い、フィールドマッピングの groupBy を設定します。

const categorizedData = [
  { Category: 'Sports', Item: 'Cricket', value: 1 },
  { Category: 'Sports', Item: 'Football', value: 2 },
  { Category: 'Games', Item: 'Chess', value: 3 },
  { Category: 'Games', Item: 'Carrom', value: 4 }
];

const fields = { 
  text: 'Item', 
  value: 'value', 
  groupBy: 'Category' 
};

<ComboBoxComponent dataSource={categorizedData} fields={fields} />

パターン 3：読み込み中のリモートデータ（セキュリティ優先）

問題： ユーザーの検索に基づいて API からデータを取得します。

セキュリティを優先した解決策： 外部 API リクエストは、レスポンスを検証およびサニタイズする信頼できるサーバー側プロキシを経由させます。クライアント側のコードにサードパーティーの URL を直接埋め込まないでください。

import { DataManager, WebApiAdaptor } from '@syncfusion/ej2-data';

// Use your server-side proxy here. The proxy should enforce allowed upstream hosts and
// sanitize responses before returning to the client.
const dataManager = new DataManager({
  url: 'https://your-trusted-proxy.example/api/search',
  adaptor: new WebApiAdaptor()
});

<ComboBoxComponent 
  dataSource={dataManager}
  fields={{ text: 'name', value: 'id' }}
  allowFiltering={true} />

パターン 4：リッチコンテンツ用のカスタムテンプレート

問題： 各項目にアイコンや追加情報を表示します。
解決策： itemTemplate プロパティを使用して、HTML の表示をカスタマイズします。

const itemTemplate = (props) => {
  return (
    <div className="flex items-center gap-2">
      <span className={`icon icon-${props.value}`}></span>
      <span>{props.name}</span>
      <small className="text-gray-500">({props.players} players)</small>
    </div>
  );
};

<ComboBoxComponent 
  dataSource={sportsData}
  itemTemplate={itemTemplate}
  fields={{ text: 'name', value: 'id' }}
/>

---

主要な Props リファレンス

Prop	Type	Description	Common Use
dataSource	Array|DataManager	表示するデータ項目	すべてのユースケース
fields	FieldSettingsModel	データフィールド（text、value、groupBy、iconCss、disabled）をマッピングします	複雑なデータ
placeholder	string	空のときに表示するヒントテキスト	UX の案内
allowCustom	boolean	リストにない値をユーザーが入力できるようにします。デフォルト：true	自由形式の入力
allowFiltering	boolean	ポップアップにフィルターバー（検索ボックス）を表示します。デフォルト：false	検索機能
enableVirtualization	boolean	大規模なデータセット向けに仮想スクロールを有効にします。<Inject services={[VirtualScroll]} /> が必要です。デフォルト：false	大規模なデータセット（5,000 件以上）
sortOrder	SortOrder	'None' | 'Ascending' | 'Descending'。デフォルト：null	並べ替えられたリスト
popupHeight	string|number	ドロップダウンの高さ（例：'300px'）。デフォルト：'300px'	レイアウトの調整
popupWidth	string|number	ドロップダウンの幅（例：'100%'）。デフォルト：'100%'	レイアウトの調整
enabled	boolean	コンポーネントを有効／無効にします。デフォルト：true	条件付きレンダリング
readonly	boolean	ユーザー入力を禁止します。デフォルト：false	表示専用モード
showClearButton	boolean	クリア（×）ボタンを表示します。デフォルト：true	選択項目のクリアを許可
change	EmitType<ChangeEventArgs>	選択が変更されたときに発生します	イベント処理
filtering	EmitType<FilteringEventArgs>	ユーザーが入力したときに発生します。カスタムのフィルターロジックに使用します	高度な検索
itemTemplate	Function|string	各リスト項目に使用するカスタム HTML	リッチな UI

---

次のステップ

1. ComboBox を初めて使いますか？ → getting-started.md から始めましょう
2. 特定のデータが必要ですか？ → data-binding.md をご覧ください
3. パフォーマンスが気になりますか？ → advanced-features.md をご確認ください
4. デザインをカスタマイズしますか？ → styling-and-theming.md をご覧ください
5. よくあるシナリオをお探しですか？ → how-to-guide.md をご覧ください（自動入力、カスケード、アイコン）
6. サイズ変更可能なドロップダウンをお探しですか？ → popup-resizing.md をお読みください
7. お困りですか？ → troubleshooting.md をご覧ください
8. API の詳細が必要ですか？ → すべてのプロパティ、メソッド、イベント、インターフェイスモデルについては、api.md をご覧ください

DropDownList

DropDownList コンポーネントは、ユーザーが単一の値を選択できる、あらかじめ定義された値のリストを提供します。ローカルおよびリモートのデータバインディング、フィルタリング、グループ化、カスタムテンプレート、仮想スクロール、アクセシビリティ、豊富なカスタマイズに対応しています。

ナビゲーションガイド

はじめに

📄 読む: references/getting-started.md

• インストールとパッケージの設定（@syncfusion/ej2-react-dropdowns）
• tailwind3 テーマの CSS インポート
• 基本的な DropDownList（関数コンポーネントとクラスコンポーネント）
• データソースのバインド
• ポップアップの高さと幅の設定

データバインディングと値のバインディング

📄 読む: references/data-binding.md

• プリミティブ配列（文字列、数値）のバインド
• fields マッピング（text、value、groupBy、iconCss）を使用した JSON オブジェクト配列のバインド
• DataManager によるリモートデータ（OData、ODataV4、WebAPI アダプター）
• 値のバインディング：値の事前選択、プリミティブと複雑なオブジェクトのバインド
• fields.disabled による個々の項目の無効化

フィルタリング

📄 参照： references/filtering.md

• 入力と同時に検索するには、allowFiltering を有効にします
• updateData を使用して filtering イベントを処理します
• デフォルトのフィルタリングを防止する — カスタムハンドラーでは、必ず args.preventDefaultAction = true を設定します
• フィルターの種類：startswith、contains、endsWith、大文字と小文字を区別するオプション
• 複数のフィールドでフィルタリングする — Predicate と .or() を使い、入力されたテキストを text と value の両方のフィールド（または任意の組み合わせ）に照合します
• 最小文字数のガードを設けたリモート／サーバーサイドフィルタリング
• ダイアクリティカルマークのフィルタリング（ignoreAccent）、デバウンス遅延
• フィルタリングされたテキストのハイライト表示、カスタム検索ロジック

グループ化とテンプレート

📄 参照： references/grouping-and-templates.md

• groupBy フィールドを使った項目のグループ化
• 固定グループヘッダーとインラインのグループヘッダー
• カスタムグループヘッダーテンプレート
• 項目テンプレート、値（選択済み）テンプレート
• ヘッダーテンプレートとフッターテンプレート
• レコードなしテンプレートとアクション失敗テンプレート

機能と設定

📄 参照： references/features-and-configuration.md

• 並べ替え（sortOrder：昇順、降順）
• 大量のリストでの仮想スクロール（enableVirtualization）
• ポップアップのサイズ変更（allowResize）
• インクリメンタル検索、クリアボタン、読み取り専用、無効化
• RTL 対応、Preact の使用

アクセシビリティ、スタイル設定、ローカライズ

📄 参照： references/accessibility-styling-localization.md

• WCAG 2.2／Section 508 への準拠
• キーボード操作のショートカット
• ARIA のロールと属性
• cssClass プロパティ — インスタンスごとにスコープされた CSS クラス、複数クラス、条件付きクラス、組み込みユーティリティクラス（e-error、e-success）
• CSS クラスのカスタマイズ（ラッパー、アイコン、ポップアップ、リスト項目、プレースホルダー）
• テーマ（tailwind3、material3、bootstrap5、fluent2）
• ローカライズ（L10n、noRecordsTemplate、actionFailureTemplate）
• RTL レイアウト（enableRtl）

API リファレンス

📄 参照： references/api.md

• 型、デフォルト値、使用例を含むプロパティの完全なリファレンス
• シグネチャ、パラメーター、戻り値の型を含むすべてのメソッド
• 引数インターフェイスと使用例を含むすべてのイベント
• インターフェイスの詳細：FieldSettingsModel、ChangeEventArgs、SelectEventArgs、PopupEventArgs、FilteringEventArgs
• プロパティ、メソッド、イベントのクイックリファレンス表

ハウツーパターン

📄 参照： references/how-to.md

• 項目の動的な追加、削除、変更
• カスケード（依存）ドロップダウン
• 複数のカスケードドロップダウン
• リモートデータの使用方法
• スクロール時にポップアップを閉じる、項目のツールチップ、項目内のアイコン
• 値変更イベント、選択した値のクリア

---

クイックスタートの例

インストール： サプライチェーンのリスクを軽減するため、パッケージを特定のメジャーバージョンに固定してください。

npm install @syncfusion/ej2-react-dropdowns@^33.x.x --save

// 1. See pinned install command above.

// 2. CSS in src/App.css
// @import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-react-dropdowns/styles/tailwind3.css";

import { DropDownListComponent } from '@syncfusion/ej2-react-dropdowns';
import './App.css';

export default function App() {
  const sportsData: string[] = ['Badminton', 'Cricket', 'Football', 'Golf', 'Tennis'];

  return (
    <DropDownListComponent
      id="ddlelement"
      dataSource={sportsData}
      placeholder="Select a game"
    />
  );
}

よく使われるパターン

フィールドマッピングを使用した JSON オブジェクトデータ

import { DropDownListComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const countryData = [
    { Id: 'au', Country: 'Australia' },
    { Id: 'br', Country: 'Brazil' },
    { Id: 'cn', Country: 'China' },
    { Id: 'in', Country: 'India' },
  ];
  const fields = { text: 'Country', value: 'Id' };

  return (
    <DropDownListComponent
      dataSource={countryData}
      fields={fields}
      placeholder="Select a country"
    />
  );
}

フィルタリング（入力と同時に検索）

import { DropDownListComponent, FilteringEventArgs } from '@syncfusion/ej2-react-dropdowns';
import { Query } from '@syncfusion/ej2-data';

export default function App() {
  const searchData = [
    { Index: 's1', Country: 'Alaska' },
    { Index: 's2', Country: 'California' },
    { Index: 's3', Country: 'Florida' },
  ];
  const fields = { text: 'Country', value: 'Index' };

  function onFiltering(args: FilteringEventArgs) {
    // Local example: updateData is applied against local `searchData` below.
    // For remote filtering, route requests through a trusted server proxy and
    // validate/sanitize responses before calling `updateData`.
    args.preventDefaultAction = true; // prevent built-in filter from running alongside custom logic
    let query = new Query();
    query = args.text !== '' ? query.where('Country', 'startswith', args.text, true) : query;
    args.updateData(searchData, query);
  }

  return (
    <DropDownListComponent
      dataSource={searchData}
      fields={fields}
      allowFiltering={true}
      filtering={onFiltering}
      placeholder="Select a country"
    />
  );
}

値を事前選択する

<DropDownListComponent
  dataSource={sportsData}
  value="Cricket"
  placeholder="Select a game"
/>

グループ化された項目

const vegetableData = [
  { Vegetable: 'Cabbage', Category: 'Leafy and Salad', Id: 'item1' },
  { Vegetable: 'Chickpea', Category: 'Beans', Id: 'item6' },
  { Vegetable: 'Garlic',   Category: 'Bulb and Stem', Id: 'item9' },
];
const fields = { groupBy: 'Category', text: 'Vegetable', value: 'Id' };

<DropDownListComponent dataSource={vegetableData} fields={fields} placeholder="Select a vegetable" />

主な Props

Prop	Type	Purpose
dataSource	any[] | DataManager	リスト項目のデータ
fields	FieldSettingsModel	text、value、groupBy、iconCss、disabled をマッピングします
value	string | number	選択済み／事前選択値
placeholder	string	入力欄のプレースホルダーテキスト
allowFiltering	boolean	検索フィルタリングを有効にします
filtering	event	カスタムフィルターロジックのハンドラー
popupHeight	string	ポップアップリストの高さ（デフォルトは自動）
popupWidth	string	ポップアップリストの幅（デフォルトは入力欄に合わせます）
sortOrder	SortOrder	'None'、'Ascending'、'Descending'
enableVirtualization	boolean	大量のデータに対する仮想スクロール
allowResize	boolean	ユーザーがサイズ変更できるポップアップ
enabled	boolean	コンポーネント全体を有効／無効にします
readonly	boolean	読み取り専用モード
showClearButton	boolean	選択をクリアする✕ボタンを表示します
enableRtl	boolean	右から左へのレイアウト

一般的なユースケース

シンプルな静的リスト → string[] を dataSource に渡すだけです。

API からのデータ → DataManager と WebApiAdaptor を使用します。references/data-binding.md を参照してください。

入力に応じた検索／フィルタリング → allowFiltering={true} を設定し、filtering イベントを処理します。references/filtering.md を参照してください。

カテゴリ分けされた項目 → groupBy フィールドをマッピングします。references/grouping-and-templates.md を参照してください。

カスタム項目レイアウト → itemTemplate を使用します。references/grouping-and-templates.md を参照してください。

大規模なデータセット（10k 以上の項目） → enableVirtualization を有効にし、VirtualScroll を注入します。references/features-and-configuration.md を参照してください。

連動するドロップダウン → 1つ目のドロップダウンの change イベントで、2つ目のドロップダウンの dataSource を再読み込みします。references/how-to.md を参照してください。

ListBox

Syncfusion ListBox コンポーネントは、スクロール可能なコンテナーに項目のリストを表示し、単一選択または複数選択を可能にします。ローカルおよびリモートのデータバインディング、ドラッグ＆ドロップによる並べ替え、フィルタリング、グループ化、カスタムテンプレート、2つのリスト間の項目移動、完全なアクセシビリティに対応しています。

ドキュメントガイド

実装のニーズに合わせて、該当するトピックを参照してください。

はじめに

📄 参照： references/getting-started.md

• React アプリのセットアップ（Vite／Create React App）
• Syncfusion パッケージのインストール
• CSS のインポートとテーマ設定
• 基本的な ListBox コンポーネントの作成
• アプリケーションの実行

選択とイベント

📄 参照： references/selection.md

• 単一選択モード
• 複数選択モード
• 選択イベントとハンドラー
• プログラムによる選択の管理
• 選択した項目の操作

データバインディングと構造

📄 参照： references/data-binding.md

• 配列およびオブジェクトのデータバインディング
• テキストと値のプロパティ
• データソースの設定
• データのグループ化
• 階層データ構造

カスタムテンプレートとアイコン

📄 参照： references/icons-and-templates.md

• 項目内のアイコンの表示
• カスタム項目テンプレート
• HTML コンテンツの表示
• テンプレート変数と構文
• 条件付き表示

高度な機能

📄 参照： references/features.md

• ドラッグ＆ドロップ機能
• フィルタリングと検索
• 並べ替えとグループ化
• Dual ListBox（転送リスト）
• スクロール設定
• 項目の有効化／無効化

スタイルと外観

📄 参照： references/style-and-appearance.md

• CSS クラスのカスタマイズ
• テーマとの統合
• 項目とグループのスタイル設定
• レスポンシブデザイン
• カスタム CSS 変数

アクセシビリティ

📄 参照： references/accessibility.md

• WCAG 2.2 準拠
• キーボードナビゲーション
• ARIA 属性
• スクリーンリーダー対応
• RTL（右から左への表示）対応

使い方ガイド

📄 読む： references/how-to-guides.md

• 項目を動的に追加する
• 項目をプログラムで選択する
• 項目を有効化／無効化する
• ListBox のデータをフィルターする
• 長いリストでスクローラーを有効にする
• フォームとの連携と送信

デュアル ListBox（転送）

📄 読む： references/dual-list-box.md

• リスト間で項目を双方向に転送する
• ツールバー操作（上／下への移動、転送）
• 権限とスキルの割り当てパターン
• カスタムスタイルとレスポンシブデザイン
• 容量制限と検証

API リファレンス

📄 読む： references/api.md

• すべてのプロパティ、その型、デフォルト値の完全な一覧
• すべてのパブリックメソッドと、パラメーターの詳細および戻り値の型
• すべてのイベントと、イベント引数インターフェイスの詳細
• サブインターフェイス：SelectionSettingsModel、ToolbarSettingsModel、FieldSettingsModel、SourceDestinationModel

---

クイックスタートの例

インストール： サプライチェーンのリスクを軽減するため、パッケージのメジャーバージョンを指定してください。

npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-base@^33.x.x

単一選択の基本的な ListBox：

import { ListBoxComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
import './App.css';

function App() {
  const data = [
    { text: 'JavaScript', id: '1' },
    { text: 'TypeScript', id: '2' },
    { text: 'React', id: '3' },
    { text: 'Vue', id: '4' },
    { text: 'Angular', id: '5' }
  ];

  const handleChange = (e) => {
    console.log('Selected:', e.value);
  };

  return (
    <ListBoxComponent 
      dataSource={data}
      fields={{ text: 'text', value: 'id' }}
      selectionSettings={{ mode: 'Single' }}
      change={handleChange}
    />
  );
}

export default App;

---

よくあるパターン

複数選択

<ListBoxComponent 
  dataSource={data}
  selectionSettings={{ mode: 'Multiple' }}
/>

チェックボックス選択

CheckBoxSelection サービスの注入が必要です。

import { ListBoxComponent, SelectionSettingsModel, Inject, CheckBoxSelection } from '@syncfusion/ej2-react-dropdowns';

const selectionSettings: SelectionSettingsModel = { showCheckbox: true };

<ListBoxComponent dataSource={data} selectionSettings={selectionSettings}>
  <Inject services={[CheckBoxSelection]} />
</ListBoxComponent>

検索／フィルターを使用

<ListBoxComponent 
  dataSource={data}
  allowFiltering={true}
  filterBarPlaceholder="Search items"
/>

カスタム項目テンプレート

const itemTemplate = (props) => {
  return (
    <div>
      <span className="icon">{props.icon}</span>
      <span>{props.text}</span>
    </div>
  );
}

<ListBoxComponent 
  dataSource={data}
  itemTemplate={itemTemplate}
/>

項目のグループ化

<ListBoxComponent 
  dataSource={groupedData}
  fields={{ text: 'text', groupBy: 'category' }}
/>

---

主なプロパティと設定

プロパティ	用途	例
dataSource	表示する項目の配列	[{ text: 'Item', id: '1' }]
fields	データのプロパティを表示項目に対応付ける	{ text: 'name', value: 'id' }
selectionSettings	選択モードとチェックボックスの表示を定義します。showCheckbox: true の場合は、CheckBoxSelection サービスを注入します	{ mode: 'Multiple' } / { showCheckbox: true }
allowFiltering	フィルター検索ボックスを有効にします	true
allowDragAndDrop	項目のドラッグ＆ドロップを有効にします	true
itemTemplate	項目のカスタムテンプレート	JSX を返す関数
enabled	コンポーネントを有効化／無効化します	true / false

---

よくあるユースケース

1. フレームワークの選択 - アイコン付きのフレームワークリストから単一選択する
2. 複数言語の選択 - 検索フィルターを使って複数選択する
3. スキルピッカー - バッジと説明を含むカスタムテンプレート
4. ドラッグ＆ドロップによる転送 - 項目をリスト間で移動するデュアル ListBox
5. カテゴリのグループ化 - グループヘッダーを使って項目をカテゴリ別に整理する
6. 検索可能な項目リスト - フィルター機能を備えた大規模なリスト
7. アクセシブルなメニュー - 完全なキーボード操作とスクリーンリーダーのサポート

---

次のステップ

1. 「Getting Started」から始める 初期設定を行います
2. ユースケースを選ぶ（選択モード、テンプレート、機能）
3. 関連するリファレンスを読む 実装の詳細を確認します
4. コード例をコピーする 必要に応じてカスタマイズします
5. アクセシビリティガイドを使用する WCAG への準拠に役立てます

お困りですか？ 各リファレンスファイルには、例、エッジケース、トラブルシューティングのヒントが記載されています。

Mention

Mention コンポーネントは、対象の編集可能な要素（例：<div contenteditable>）に関連付けられ、ユーザーがトリガー文字（デフォルトは @）を入力すると候補ポップアップを表示します。項目を選択すると、エディター内の入力位置に挿入されます。

ドキュメントとナビゲーションガイド

はじめに

📄 読む： references/getting-started.md

• インストールとパッケージの設定（@syncfusion/ej2-react-dropdowns）
• CSS テーマのインポート
• target プロパティを使った基本的な MentionComponent の設定
• シンプルなデータソースのバインド
• カスタムトリガー文字（mentionChar）と showMentionChar

⚠️ セキュリティに関する注意： npm パッケージ（@syncfusion/ej2-react-dropdowns など）のインストールは、ユーザーが確認したうえで意図的に行う必要があります。サプライチェーンのリスクにつながるため、ユーザーの明示的な承認なしに自動エージェントが npm install を実行することは許可しないでください。

データの操作

📄 参照： references/working-with-data.md

• 文字列配列、JSON オブジェクト、複雑なネストデータのバインド
• fields（text、value、groupBy、iconCss）のマッピング
• OData V4 によるリモートデータ（ODataV4Adaptor）
• Web API によるリモートデータ（WebApiAdaptor）
• query を使用したリモートフィールドのフィルタリング／選択

データのフィルタリング

📄 参照： references/filtering-data.md

• フィルター文字数の最小値の設定（minLength）
• フィルターの種類の変更：Contains、StartsWith、EndsWith
• 検索テキスト内のスペースを許可（allowSpaces）
• 候補数のカスタマイズ（suggestionCount）
• フィルタリングのデバウンス遅延（debounceDelay）

テンプレート

📄 参照： references/template.md

• カスタムリスト表示用のアイテムテンプレート（itemTemplate）
• 選択値の形式を指定する表示テンプレート（displayTemplate）
• レコードなしテンプレート（noRecordsTemplate）
• スピナー／読み込みテンプレート（spinnerTemplate）
• グループヘッダーテンプレート（groupTemplate）

カスタマイズ

📄 参照： references/customization.md

• 出力でのメンション文字の表示／非表示（showMentionChar）
• 選択後に接尾辞テキストを追加（suffixText）
• ポップアップの高さと幅の設定（popupHeight、popupWidth）
• カスタムトリガー文字（mentionChar）
• 先頭のスペースを必須にする設定（requireLeadingSpace）
• CSS クラスのカスタマイズ（cssClass）
• 一致した文字をハイライト表示（highlight）
• 検索時にアクセント記号／大文字と小文字を区別しない（ignoreAccent、ignoreCase）
• ポップアップの Z インデックス（zIndex）

並べ替え

📄 参照： references/sorting.md

• 候補リストの並べ替え：Ascending、Descending、None

無効な項目

📄 参照： references/disabled-items.md

• fields.disabled による項目の無効化
• disableItem() メソッドによる項目の動的な無効化

アクセシビリティ

📄 参照： references/accessibility.md

• WAI-ARIA 属性（aria-selected、aria-activedescendent、aria-owns）
• キーボード操作のショートカット
• WCAG 2.2 および Section 508 への準拠
• RTL のサポート（enableRtl）

ローカライズ

📄 参照： references/localization.md

• L10n による noRecordsTemplate テキストのローカライズ
• locale プロパティの設定

API リファレンス

📄 参照： references/api.md

• すべてのプロパティ、メソッド、イベント
• target、dataSource、fields、mentionChar、minLength、suggestionCount
• メソッド：addItem、disableItem、getDataByValue、getItems、showPopup、hidePopup、search、destroy
• イベント：select、change、filtering、beforeOpen、opened、closed、dataBound、actionBegin、actionComplete、actionFailure

クイックスタートの例

import { MentionComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

// CSS imports
// @import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-react-dropdowns/styles/tailwind3.css";

function App() {
  const mentionTarget = '#commentBox';
  const users = [
    { Name: 'Selma Rose', EmailId: '[email protected]' },
    { Name: 'Robert', EmailId: '[email protected]' },
    { Name: 'William', EmailId: '[email protected]' },
  ];
  const fields = { text: 'Name' };

  return (
    <div>
      <label>Comments</label>
      <div id="commentBox" placeholder="Type @ to mention a user"></div>
      <MentionComponent
        target={mentionTarget}
        dataSource={users}
        fields={fields}
      />
    </div>
  );
}

export default App;

よくあるパターン

カスタムトリガー文字

mentionChar を使用すると、@ の代わりに # でトリガーできます：

<MentionComponent
  target="#editor"
  dataSource={tags}
  mentionChar="#"
  showMentionChar={true}
/>

フィルタリングを使用したリモートデータ（セキュリティ優先）

import { DataManager, ODataV4Adaptor, Query } from '@syncfusion/ej2-data';

// SECURITY: Do not call third-party endpoints from the browser. Use a server-side
// proxy that you control and that validates/sanitizes upstream responses.
const dataSource = new DataManager({
  url: 'https://your-trusted-proxy.example/api/mentions',
  adaptor: new ODataV4Adaptor(),
  crossDomain: true,
});
const query = new Query().from('Customers').select(['ContactName', 'CustomerID']).take(6);
const fields = { text: 'ContactName', value: 'CustomerID' };

<MentionComponent
  target="#editor"
  dataSource={dataSource}
  fields={fields}
  query={query}
  minLength={2}
  popupWidth="250px" />

選択イベントの処理

import { SelectEventArgs } from '@syncfusion/ej2-react-dropdowns';

function onSelect(args: SelectEventArgs) {
  console.log('Selected item:', args.itemData);
  console.log('Selected text:', args.text);
}

<MentionComponent
  target="#editor"
  dataSource={users}
  fields={{ text: 'Name' }}
  select={onSelect}
/>

ポップアップの設定

<MentionComponent
  target="#editor"
  dataSource={data}
  fields={{ text: 'Name' }}
  popupHeight="200px"
  popupWidth="300px"
  suggestionCount={10}
  sortOrder="Ascending"
  suffixText="&nbsp;"
/>

主要な Props の概要

Prop	型	デフォルト	目的
target	string|HTMLElement	—	編集可能な領域を指定する CSS セレクターまたは要素
dataSource	array|DataManager	[]	候補データ
fields	FieldSettingsModel	{text:null,value:null}	データフィールドをマッピングします
mentionChar	string	'@'	トリガー文字
showMentionChar	boolean	false	挿入するテキストの先頭にトリガー文字を付けます
minLength	number	0	検索を開始するまでの最小文字数
suggestionCount	number	25	ポップアップに表示する項目の最大数
filterType	FilterType	'Contains'	フィルターの一致方式
allowSpaces	boolean	false	検索でスペースを許可します
sortOrder	SortOrder	'None'	並べ替え順
popupHeight	string|number	'300px'	ポップアップの高さ
popupWidth	string|number	'auto'	ポップアップの幅
suffixText	string	null	選択後に追加するテキスト
requireLeadingSpace	boolean	true	トリガー文字の前にスペースが必要かどうか
highlight	boolean	false	検索文字を強調表示します

MultiSelect

MultiSelect Dropdown コンポーネントを実装するための包括的なスキルです。フィルタリング、グループ化、テンプレート、チェックボックス、チップ、仮想スクロールなどを利用して、ユーザーがリストから複数の値を選択できるようにします。

コンポーネントの概要

インストール： サプライチェーンのリスクを軽減するため、パッケージは特定のメジャーバージョンに固定してください。

npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-base@^33.x.x @syncfusion/ej2-buttons@^33.x.x @syncfusion/ej2-inputs@^33.x.x

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';
// Also import base dependencies:
// @syncfusion/ej2-base/styles/tailwind3.css
// @syncfusion/ej2-buttons/styles/tailwind3.css
// @syncfusion/ej2-inputs/styles/tailwind3.css

パッケージ： @syncfusion/ej2-react-dropdowns
メインコンポーネント： MultiSelectComponent
チェックボックスモジュール： CheckBoxSelection（<Inject services={[CheckBoxSelection]} /> で挿入します）
仮想スクロールモジュール： VirtualScroll（<Inject services={[VirtualScroll]} /> で挿入します）

クイックスタートの例

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

export default function App() {
  const sportsData = ['Badminton', 'Basketball', 'Cricket', 'Football', 'Golf', 'Tennis'];

  return (
    <MultiSelectComponent
      id="multiselect"
      dataSource={sportsData}
      placeholder="Select sports"
    />
  );
}

オブジェクトとフィールドマッピングを使用する場合：

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

export default function App() {
  const sportsData = [
    { id: 'game1', sports: 'Badminton' },
    { id: 'game2', sports: 'Football' },
    { id: 'game3', sports: 'Tennis' },
  ];
  const fields = { text: 'sports', value: 'id' };

  return (
    <MultiSelectComponent
      id="multiselect"
      dataSource={sportsData}
      fields={fields}
      placeholder="Select a game"
    />
  );
}

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• インストールとパッケージのセットアップ（Vite / CRA）
• CSS のインポートとテーマ設定
• 基本的な MultiSelect の実装（クラスコンポーネントと関数コンポーネント）
• シンプルなデータソースのバインド
• ポップアップの高さ／幅の設定

データバインディング

📄 参照： references/data-binding.md

• 文字列配列とオブジェクト配列の違い
• フィールドマッピング（text、value、groupBy、iconCss、disabled）
• DataManager によるリモートデータ（OData、OData V4、Web API）
• JSON／JSONP 形式
• 複雑なデータバインディングにおける注意点

グループ化

📄 参照： references/grouping.md

• groupBy で項目をカテゴリ別にグループ化
• インラインまたは固定のグループヘッダー
• グループヘッダーのテンプレート
• 並べ替えと複数階層のグループ化

フィルタリング

📄 参照： references/filtering.md

• allowFiltering の有効化
• filtering イベントの処理
• where() 条件を使用する Query API
• フィルターの種類：startswith、contains、endswith
• 大文字と小文字の区別、複数の条件、パフォーマンス

テンプレート

📄 参照： references/templates.md

• カスタムのリスト項目レイアウト用の項目テンプレート
• 選択内容の表示に使う値／チップテンプレート
• グループヘッダーのテンプレート
• ヘッダー、フッター、レコードなし、アクション失敗時のテンプレート

選択モードと機能

📄 参照： references/selection-and-features.md

• チェックボックスモード（CheckBoxSelection を挿入）
• チップ／タグの表示と tagging イベント
• カスタム値（allowCustomValue）
• 値のバインド（プリミティブ型とオブジェクト型）
• fields.disabled による項目の無効化
• ポップアップのサイズ変更（allowResize）
• 大規模なデータセット向けの仮想スクロール（VirtualScroll を挿入）

アクセシビリティ、スタイル設定、ローカライズ

📄 参照： references/accessibility-styling-localization.md

• WAI-ARIA 属性とキーボードショートカット
• WCAG 2.2／Section 508／スクリーンリーダーのサポート
• CSS のカスタマイズ（チップ、ラッパー、アイコン、区切り文字）
• RTL のサポート
• L10n によるローカライズ

API リファレンス

📄 参照： references/api.md

• すべてのプロパティの型、説明、デフォルト値を網羅した一覧
• すべてのパブリックメソッドのパラメーター詳細と戻り値の型
• すべてのイベントの引数の型と発生条件

主な Props のリファレンス

Prop	型	使用するタイミング
dataSource	string[] | object[] | DataManager	必須です。表示するデータを指定します
fields	FieldSettingsModel	オブジェクトデータを使用するときに指定します。text、value、groupBy、disabled をマッピングします
mode	'Default' | 'Box' | 'CheckBox' | 'Delimiter'	選択項目の表示を変更します。チップ（Box）、チェックボックス、カンマ区切りから選べます
value	string[] | number[] | object[]	読み込み時に項目を事前選択します
allowFiltering	boolean	入力しながらの検索フィルタリングを有効にします
allowCustomValue	boolean	リストにない値をユーザーが入力できるようにします
allowObjectBinding	boolean	プリミティブ値の代わりに、選択した値としてオブジェクト全体を返します
enableVirtualization	boolean	500 件以上の項目でパフォーマンスを向上させるために使用します
allowResize	boolean	ユーザーがポップアップのサイズを変更できるようにします
popupHeight	string	ポップアップリストの高さを制限します（デフォルト：300px）
popupWidth	string	ポップアップの幅を設定します（デフォルト：入力欄に合わせます）
placeholder	string	入力欄のプレースホルダーテキスト

よくあるユースケース

複数タグ入力（チップ表示）： → mode="Box"（デフォルト）を使用します。選択項目ごとにチップが表示されます。

チェックボックスによる複数選択： → mode="CheckBox" を使用し、CheckBoxSelection モジュールをインジェクトします。

長いリストの検索／フィルタリング： → allowFiltering={true} を設定し、リモートデータの場合は filtering イベントを処理します。

値の事前選択： → 値フィールドの値を配列として value prop に渡します：value={['id1', 'id2']}。

カテゴリ別のグループ化： → fields prop に groupBy を追加します：fields={{ text: 'name', value: 'id', groupBy: 'category' }}。

大規模なデータセット（1000 件以上）： → enableVirtualization={true} を設定し、VirtualScroll モジュールをインジェクトします。

特定のオプションを無効化： → データに boolean 型の disabled 列を追加し、マッピングします：fields={{ ..., disabled: 'isDisabled' }}。

リストにない値のカスタム入力： → allowCustomValue={true} を設定し、カスタム操作のために customValueSelection イベントを処理します。

選択ガイド

User wants multiple selections?
  ├── Visual chips with filter → mode="Box" (default) + allowFiltering
  ├── Checkbox-style list      → mode="CheckBox" + Inject CheckBoxSelection
  └── Comma-separated display  → mode="Delimiter"

Data source type?
  ├── Simple strings/numbers   → Pass array directly to dataSource
  ├── Objects                  → Pass array + fields={{ text, value }}
  └── Remote API               → Use DataManager + allowFiltering + filtering event

List is very long?
  └── Yes (500+) → enableVirtualization={true} + Inject VirtualScroll

Need custom item layout?
  └── Use itemTemplate, valueTemplate, groupTemplate props

Need localization?
  └── Read references/accessibility-styling-localization.md

MultiColumn ComboBox

Syncfusion の MultiColumnComboBoxComponent は、複数列のポップアップグリッドを備えたコンボボックスを表示し、構造化された表形式のデータから選択できるようにします。ローカルデータとリモートデータ、フィルタリング、並べ替え、グループ化、テンプレート、仮想化、および完全なアクセシビリティ準拠に対応しています。

パッケージ： @syncfusion/ej2-react-multicolumn-combobox

ナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• インストールとパッケージのセットアップ
• CSS のインポートとテーマの設定（Tailwind 3）
• 最初の MultiColumnComboBoxComponent のレンダリング
• ColumnDirective を使用した dataSource、fields、columns のバインド
• popupHeight と popupWidth の設定
• 最小限の動作例（関数コンポーネントとクラスコンポーネント）

列

📄 参照： references/columns.md

• ColumnDirective と ColumnsDirective による列の定義
• field、header、width — 列の基本プロパティ
• 列のテキスト配置を指定する textAlign
• セル単位でカスタムレンダリングする template
• boolean 型の列に使用する displayAsCheckBox
• 列の CSS をカスタマイズする customAttributes
• カスタム列ヘッダーに使用する headerTemplate
• データの書式設定に使用する format

データバインディング

📄 参照： references/data-binding.md

• dataSource を使用してローカルのオブジェクト配列をバインドする
• DataManager と WebApiAdaptor を使用してリモートデータをバインドする
• fields（text、value、groupBy）をマッピングする
• query プロパティを使用して、データセットをフィルタリングまたは制限する
• OData、OData V4、Web API アダプターのパターン

フィルタリング

📄 参照： references/filtering.md

• allowFiltering でフィルタリングを有効または無効にする
• filterType（StartsWith、EndsWith、Contains）でフィルターモードを変更する
• カスタムフィルターロジックには filtering イベントを使用する
• 読み取り専用のシナリオではフィルタリングを無効にする

並べ替え

📄 参照： references/sorting.md

• allowSorting で並べ替えを有効にする
• sortOrder（None、Ascending、Descending）で初期の並べ替え順序を設定する
• sortType（OneColumn、MultipleColumns）で複数の列を並べ替える
• 列ヘッダーをクリックして並べ替え方向を切り替える

グループ化

📄 参照： references/grouping.md

• fields.groupBy でデータをグループ化する
• ポップアップにグループヘッダーを固定表示する
• groupTemplate を使用してグループヘッダーをカスタマイズする

テンプレート

📄 参照： references/templates.md

• 各行をカスタマイズする itemTemplate
• カスタム列ヘッダーを設定する headerTemplate（ColumnDirective 上）
• グループヘッダーをカスタマイズする groupTemplate
• ポップアップのフッターコンテンツを設定する footerTemplate
• 空の状態を表示する noRecordsTemplate
• リモートデータの取得エラー状態を表示する actionFailureTemplate

項目と設定

📄 参照： references/items.md

• text、value、index で初期選択を設定する
• 入力ラベルの動作には placeholder と floatLabelType を使用する
• 選択を解除できるようにする showClearButton
• disabled 状態と readonly 状態
• サイズ設定用の width、popupWidth、popupHeight
• カスタムスタイル用の cssClass
• 追加の HTML 属性用の htmlAttributes
• グリッド線、行の高さ、交互の行用の gridSettings
• データ制約用の query
• addItems メソッド、focusIn、focusOut、showPopup、hidePopup

仮想化

📄 参照： references/virtualization.md

• 大規模なデータセットで enableVirtualization を有効にする
• ローカルデータとリモートデータで仮想スクロールを使用する
• gridSettings.rowHeight と組み合わせる

イベント

📄 参照： references/events.md

• change — 値が変更されたとき、または項目が選択されたときに発生します
• select — 項目が選択されたときに発生します
• open / close — ポップアップの開閉時のライフサイクル
• filtering — カスタムフィルタリングのため、文字が入力されたときに発生します
• actionBegin / actionComplete / actionFailure — データ取得時のライフサイクル

API リファレンス

📄 参照： references/api.md

• 型とデフォルト値を含む、すべてのプロパティの一覧
• 引数の型を含む、すべてのイベント
• すべてのメソッド：addItems、focusIn、focusOut、getDataByValue、getItems、showPopup、hidePopup
• ColumnModel のプロパティ
• GridSettingsModel のプロパティ
• FieldSettingsModel のプロパティ

アクセシビリティ

📄 参照： references/accessibility.md

• WCAG 2.2 および Section 508 への準拠
• WAI-ARIA 属性（role、aria-expanded、aria-selected など）
• キーボードナビゲーションのショートカット
• enableRtl による RTL のサポート
• スクリーンリーダーのサポート

ローカライズ

📄 参照： references/localization.md

• L10n を使用して noRecordsTemplate のテキストをローカライズする
• 文化圏に応じた表示には locale プロパティを設定する
• 翻訳オブジェクトを読み込む

クイックスタート

import { MultiColumnComboBoxComponent, ColumnsDirective, ColumnDirective } from '@syncfusion/ej2-react-multicolumn-combobox';
import * as React from 'react';
import './App.css';

// CSS in App.css:
// @import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-grids/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-popups/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-react-multicolumn-combobox/styles/tailwind3.css";

function App() {
  const empData = [
    { EmpID: 1001, Name: 'Andrew Fuller', Designation: 'Team Lead', Country: 'England' },
    { EmpID: 1002, Name: 'Robert', Designation: 'Developer', Country: 'USA' },
    { EmpID: 1003, Name: 'Michael', Designation: 'HR', Country: 'Russia' },
  ];
  const fields = { text: 'Name', value: 'EmpID' };

  return (
    <MultiColumnComboBoxComponent
      id="multicolumn"
      dataSource={empData}
      fields={fields}
      placeholder="Select an employee"
    >
      <ColumnsDirective>
        <ColumnDirective field='EmpID' header='Employee ID' width={120} />
        <ColumnDirective field='Name' header='Name' width={120} />
        <ColumnDirective field='Designation' header='Designation' width={120} />
        <ColumnDirective field='Country' header='Country' width={100} />
      </ColumnsDirective>
    </MultiColumnComboBoxComponent>
  );
}
export default App;

よく使われるパターン

テキストで項目を事前選択する

<MultiColumnComboBoxComponent dataSource={empData} fields={fields} text="Michael">
  {/* columns */}
</MultiColumnComboBoxComponent>

Contains モードでフィルタリングを有効にする

<MultiColumnComboBoxComponent
  dataSource={empData}
  fields={fields}
  allowFiltering={true}
  filterType="Contains"
>
  {/* columns */}
</MultiColumnComboBoxComponent>

複数列に対応した降順ソートを有効にする

import { SortOrder } from '@syncfusion/ej2-react-multicolumn-combobox';

<MultiColumnComboBoxComponent
  dataSource={empData}
  fields={fields}
  allowSorting={true}
  sortOrder={SortOrder.Descending}
  sortType="MultipleColumns"
>
  {/* columns */}
</MultiColumnComboBoxComponent>

値の変更イベントを処理する

<MultiColumnComboBoxComponent
  dataSource={empData}
  fields={fields}
  change={(args) => console.log('Selected:', args.value)}
>
  {/* columns */}
</MultiColumnComboBoxComponent>