sgds-components

SGDS コンポーネントのセットアップスキル

<sgds-*> Web コンポーネントを使用するための前提条件とフレームワークとの統合方法です。

インストール

npm install @govtechsg/sgds-web-component
# or
pnpm add @govtechsg/sgds-web-component

アプリのエントリーポイントでライブラリを一度だけインポートします。

import "@govtechsg/sgds-web-component";

フレームワークとの統合

React

使用するインポート方法は React のバージョンによって異なります。

React 19 以降（クライアントサイド、例：Vite）

React 19 はカスタム要素をネイティブで直接サポートしています。アプリのエントリーポイントで一度インポートすれば、Web コンポーネントのタグをどこでも使用できます。

import "@govtechsg/sgds-web-component";

function App() {
  return (
    <sgds-button variant="primary" onsgds-blur={(e) => console.log(e)}>
      Click Me
    </sgds-button>
  );
}

React 19 のカスタムイベント構文：イベント名の先頭に小文字の on を付けます（sgds-blur → onsgds-blur）。

Next.js を使用していますか？ Next.js は SSR ベースで、異なるセットアップが必要です。以下のNext.js セクションを参照してください。

複雑なプロパティ（配列、オブジェクト）は宣言的に渡せます。

import "@govtechsg/sgds-web-component";

const steps = [
  { component: <Step1 />, stepHeader: "Personal details" },
  { component: <Step2 />, stepHeader: "Contact details" },
];

function App() {
  return <sgds-stepper steps={steps}></sgds-stepper>;
}

React 18 以前

React ≤18 はカスタム要素のイベントや複雑なプロパティをネイティブでサポートしていません。React ラッパーコンポーネントを使用してください。

import { SgdsButton } from "@govtechsg/sgds-web-component/react";

function App() {
  return (
    <SgdsButton variant="primary" onSgdsBlur={(e) => console.log(e)}>
      Click Me
    </SgdsButton>
  );
}

React ラッパーのイベント名：sgds-blur → onSgdsBlur、sgds-change → onSgdsChange（on を付け、ハイフンで区切られた各単語をキャメルケースにします）。

React ≤18 でのコンポーネントメソッドへのアクセス（useRef を使用）：

import { useRef } from "react";
import type { SgdsStepper as SStep } from "@govtechsg/sgds-web-component/components";
import SgdsStepper from "@govtechsg/sgds-web-component/react/stepper/index.js";

function StepperComponent() {
  const stepperRef = useRef<SStep>(null);
  return <SgdsStepper steps={steps} ref={stepperRef} />;
}

注：Next.js や SSR フレームワークでは、初回読み込み時のハイドレーションのタイミングに関する問題を解決できるため、React ラッパーの使用を推奨します。

公式ドキュメント：https://webcomponent.designsystem.tech.gov.sg/?path=/docs/frameworks-react--docs

---

Next.js

Next.js は SSR フレームワークです。Web コンポーネントはブラウザー API に依存するため、サーバーサイドレンダリング中にモジュールレベルでインポートすると、ハイドレーションの問題が発生することがあります。

推奨する方法：React ラッパーコンポーネントを使用する。 React ラッパーを使用すると、初回ページ読み込み時にイベントリスナーが機能しなくなる原因となるハイドレーションのタイミングに関する問題を解決できます。インポートして使用するだけです。

'use client';
import { SgdsInput, SgdsButton } from "@govtechsg/sgds-web-component/react";

export default function MyForm() {
  return (
    <>
      <SgdsInput label="Name" onSgdsChange={(e) => console.log(e)} />
      <SgdsButton variant="primary">Submit</SgdsButton>
    </>
  );
}

イベント名はキャメルケースの規則に従います：sgds-change → onSgdsChange、sgds-after-show → onSgdsAfterShow。

TypeScript のサポート — プロジェクトのルートに types.d.ts を追加し、SGDS React の型定義を参照します。これにより、すべての sgds-* 要素でプロパティの完全な IntelliSense と、型付けされた CustomEvent の詳細ペイロードを利用できます。

tsconfig に含まれる任意の .d.ts ファイルで ES インポートを使用します。

import "@govtechsg/sgds-web-component/types/react";

詳細については、Next.js の公式統合ドキュメントを参照してください。

---

Vue

Vue 3 は Web コンポーネントをネイティブでサポートしています。SGDS 固有のラッパーはありません。設定については、Vue と Web コンポーネントのドキュメントを参照してください。未知の要素に関する警告を抑制する SGDS 固有のフィルターは tag.startsWith("sgds-") です。

---

Angular

Angular は CUSTOM_ELEMENTS_SCHEMA を使用して Web コンポーネントをネイティブでサポートしています。SGDS 固有のラッパーはありません。設定については、Angular elements のドキュメントを参照してください。

---

コンポーネントの動作に関するトラブルシューティング

コンポーネントが予期しない動作をする場合（誤ったイベントが発火する、プロパティが反映されない、スロットがレンダリングされないなど）は、コンパイル済みのソースを直接確認してください。ソースには、ドキュメントには記載されていない、メソッド本体、イベントのロジック、内部のデフォルト値、エッジケースの処理がすべて含まれています。

node_modules/@govtechsg/sgds-web-component から読み取ってください。このディレクトリはパッケージのインストール後に存在します。

node_modules/@govtechsg/sgds-web-component/components/Accordion/sgds-accordion.js
node_modules/@govtechsg/sgds-web-component/components/Accordion/sgds-accordion-item.js
node_modules/@govtechsg/sgds-web-component/components/Accordion/sgds-accordion.d.ts

Accordion/sgds-accordion を、該当するコンポーネントのフォルダー名とファイル名に置き換えてください。.js ファイルには実装全体が含まれ、.d.ts ファイルにはすべてのプロパティ、型、イベント、スロット、JSDoc の説明が記載されています。

node_modules が存在しない場合 — パッケージがインストールされていません。ソースファイルを確認する前に、通常のインストール手順（npm install / pnpm install）を実行するようユーザーに依頼してください。

---

AI エージェント向け：主な判断基準は、React のバージョンとレンダリングモードです。

• Next.js（SSR）：React ラッパーコンポーネント（@govtechsg/sgds-web-component/react の SgdsInput、SgdsButton など）を使用してください。初回ロード時のハイドレーションのタイミングに関する問題を解決できます。イベントの props にはキャメルケース（onSgdsChange）を使用します。
• React 19 以降の CSR（Vite など）：ネイティブの <sgds-*> タグと onsgds-change 構文、または onSgdsChange を使う React ラッパーのどちらも使用でき、同様に動作します。
• React 18 以下：SGDS React ラッパーコンポーネントを使用し、イベントの props にはキャメルケース（onSgdsChange）を使用します。
• Vue / Angular：標準的な Web コンポーネントの統合を使用します。Vue 固有の SGDS の詳細として、未知の要素に関する警告を抑制するには tag.startsWith("sgds-") を使用します。

ユーザーからコンポーネントの予期しない動作（誤ったイベント、プロパティが反映されない、スロットがレンダリングされないなど）の報告があった場合は、他の対応を試す前にコンパイル済みのソースを読むよう案内してください。上記のコンポーネントの動作に関するトラブルシューティングのセクションを参照してください。

全般的なルール — SGDS コンポーネントに幅を明示的に設定しないでください。 いずれの <sgds-*> 要素にも、width、style="width: ..."、固定幅のユーティリティクラス（例：sgds:w-40）を直接追加しないでください。幅は親レイアウトで制御します。幅を制限するには、フレックス、グリッド、またはラッパーの div を使用してください。例外は、ユーザーが固定幅を明示的に指定した場合のみです。

---

Available Components

Category	Component	Reference
Actions	Button	→ reference/button.md
Actions	Icon Button	→ reference/icon-button.md
Actions	Close Button	→ reference/close-button.md
Actions	Link	→ reference/link.md
Actions	Dropdown	→ reference/dropdown.md
Actions	Overflow Menu	→ reference/overflow-menu.md
Navigation	Masthead	→ reference/masthead.md
Navigation	Main Nav	→ reference/mainnav.md
Navigation	Footer	→ reference/footer.md
Navigation	Breadcrumb	→ reference/breadcrumb.md
Navigation	Pagination	→ reference/pagination.md
Navigation	Sidenav	→ reference/sidenav.md
Navigation	Sidebar	→ reference/sidebar.md
Navigation	Subnav	→ reference/subnav.md
Navigation	Tab	→ reference/tab.md
Navigation	Table of Contents	→ reference/table-of-contents.md
Layout	Accordion	→ reference/accordion.md
Layout	Divider	→ reference/divider.md
Layout	Drawer	→ reference/drawer.md
Layout	Modal	→ reference/modal.md
Content	Badge	→ reference/badge.md
Content	Card	→ reference/card.md
Content	Icon Card	→ reference/icon-card.md
Content	Image Card	→ reference/image-card.md
Content	Thumbnail Card	→ reference/thumbnail-card.md
Content	Description List	→ reference/description-list.md
Content	Data Table	→ reference/data-table.md
Content	Icon	→ reference/icon.md
Content	Icon List	→ reference/icon-list.md
Content	Table	→ reference/table.md
Content	Tooltip	→ reference/tooltip.md
Forms	Input	→ reference/input.md
Forms	Textarea	→ reference/textarea.md
Forms	Select	→ reference/select.md
Forms	Checkbox	→ reference/checkbox.md
Forms	Radio	→ reference/radio.md
Forms	Combo Box	→ reference/combo-box.md
Forms	Datepicker	→ reference/datepicker.md
Forms	File Upload	→ reference/file-upload.md
Forms	Quantity Toggle	→ reference/quantity-toggle.md
Feedback	Switch	→ reference/switch.md
Workflow	Stepper	→ reference/stepper.md

---

フォーム入力コンポーネント

フォームを作成する際は、以下の9つのフォーム入力コンポーネントを使用してユーザーデータを収集してください。

1. <sgds-input> — テキストフィールド
2. <sgds-textarea> — 複数行のテキスト
3. <sgds-select> — ドロップダウン選択
4. <sgds-checkbox> / <sgds-checkbox-group> — 複数選択
5. <sgds-radio> / <sgds-radio-group> — 単一選択
6. <sgds-combo-box> — 検索可能な選択
7. <sgds-datepicker> — 日付入力
8. <sgds-file-upload> — ファイル選択
9. <sgds-quantity-toggle> — 数値カウンター

フォームでは使用しないでください（これらは入力ではなく、フィードバック／状態表示用です）：

• <sgds-switch> — これはフィードバックコンポーネント（トグル状態を表示するもの）であり、フォーム入力ではありません。ユーザーの選択を収集するには、代わりに <sgds-checkbox> または <sgds-radio-group> を使用してください。
• その他の入力以外のコンポーネント（Alert、Badge、Button、Card など）— これらはレイアウト／フィードバック用であり、フォームコントロールではありません。

フォームのレイアウトパターン（フィールドの組み合わせ、間隔、幅の制約、<sgds-stepper> を使った複数ステップフォーム、ヘッダーの階層）については、sgds-blocks のフォームレイアウトスキルを参照してください。 | フィードバック | Alert | → reference/alert.md | | フィードバック | Spinner | → reference/spinner.md | | フィードバック | Skeleton | → reference/skeleton.md | | フィードバック | Progress Bar | → reference/progress-bar.md | | フィードバック | Toast | → reference/toast.md | | フィードバック | System Banner | → reference/system-banner.md |