# Sgds Components

> Complete reference for all SGDS web components including installation and framework integration. Use when users ask about any <sgds-*> component — accordion, alert, badge, breadcrumb, button, card, checkbox, close-button, combo-box, data-table, datepicker, description-list, divider, drawer, dropdown, file-upload, footer, icon, icon-button, icon-card, icon-list, image-card, input, link, mainnav, masthead, modal, overflow-menu, pagination, progress-bar, quantity-toggle, radio, select, sidebar, sidenav, skeleton, spinner, stepper, subnav, switch, system-banner, tab, table, table-of-contents, textarea, thumbnail-card, toast, or tooltip. Also covers React 19+, React ≤18, Vue, Angular, and Next.js integration.

- Skill: `govtechsg/sgds-components` (Agent Skill, multi-file: 49 files)
- Install (CLI): `npx skillmds@latest add govtechsg/sgds-components`
- Raw SKILL.md: https://api.skillmd.com/api/skills/govtechsg/sgds-components/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: govtechsg (https://skillmd.com/u/govtechsg)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/govtechsg/sgds-components

---


# SGDS Components Setup Skill

Prerequisites and framework integration for using `<sgds-*>` web components.

## Installation

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

Import the library once at your app entry point:

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

## Framework Integration

### React

**React version determines which import to use.**

#### React 19+ (client-side, e.g. Vite)

React 19 supports native custom elements directly — import once at the app entry point, then use the web component tag anywhere:

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

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

Custom event syntax in React 19: prefix the event name with `on` in lowercase (`sgds-blur` → `onsgds-blur`).

> **Using Next.js?** Next.js is SSR-based and requires a different setup — see the [Next.js section](#nextjs) below.

Complex props (arrays, objects) can be passed declaratively:

```jsx
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 and below

React ≤18 does not support custom element events or complex props natively. Use the React wrapper components:

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

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

React wrapper event naming: `sgds-blur` → `onSgdsBlur`, `sgds-change` → `onSgdsChange` (prefix `on`, camelCase applies to every hyphen-separated word).

**Accessing component methods in React ≤18** (via `useRef`):

```tsx
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} />;
}
```

> **Note**: For Next.js and SSR frameworks, React wrappers are the recommended approach as they resolve hydration timing issues on initial load.

Official docs: https://webcomponent.designsystem.tech.gov.sg/?path=/docs/frameworks-react--docs

---

### Next.js

Next.js is an SSR framework — web components rely on browser APIs and can cause hydration issues when imported at the module level during server-side rendering.

**Recommended approach: Use React wrapper components.** The React wrappers resolve hydration timing issues that cause event listeners to fail on initial page load — just import and use:

```tsx
'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>
    </>
  );
}
```

Event naming follows the camelCase convention: `sgds-change` → `onSgdsChange`, `sgds-after-show` → `onSgdsAfterShow`.

**TypeScript support** — add a `types.d.ts` at the project root and reference the SGDS React type definitions. This gives full IntelliSense for props and typed `CustomEvent` detail payloads on all `sgds-*` elements:

Use an ES import in any `.d.ts` file included by your `tsconfig`:

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

See the [official Next.js integration docs](https://webcomponent.designsystem.tech.gov.sg/?path=/docs/frameworks-react--docs) for more detail.

---

### Vue

Vue 3 supports web components natively — no SGDS-specific wrappers exist. Refer to the [Vue + web components documentation](https://vuejs.org/guide/extras/web-components) for configuration. The SGDS-specific filter for suppressing unknown element warnings is `tag.startsWith("sgds-")`.

---

### Angular

Angular supports web components natively via `CUSTOM_ELEMENTS_SCHEMA` — no SGDS-specific wrappers exist. Refer to the [Angular elements documentation](https://angular.io/guide/elements) for configuration.

---

## Troubleshooting Component Behaviour

When a component behaves unexpectedly — wrong event fired, property not reflected, slot not rendering — read the compiled source directly. It contains full method bodies, event logic, internal defaults, and edge-case handling that no documentation captures.

Read from `node_modules/@govtechsg/sgds-web-component` — this directory is present once the package is installed:

```
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
```

Replace `Accordion/sgds-accordion` with the relevant component folder and file name. The `.js` file contains the full implementation; the `.d.ts` file lists all properties, types, events, slots, and JSDoc descriptions.

**If `node_modules` is absent** — the package has not been installed. Ask the user to run their normal install step (`npm install` / `pnpm install`) before inspecting source files.

---

**For AI agents**: The primary decision tree is React version + rendering mode:
- **Next.js (SSR)**: Use React wrapper components (`SgdsInput`, `SgdsButton`, etc. from `@govtechsg/sgds-web-component/react`) — they resolve hydration timing issues on initial load. Event props use camelCase (`onSgdsChange`).
- **React 19+ CSR (Vite etc.)**: Either native `<sgds-*>` tags with `onsgds-change` syntax, or React wrappers with `onSgdsChange` — both work equally well.
- **React ≤18**: SGDS React wrapper components, camelCase event props (`onSgdsChange`)
- **Vue / Angular**: standard web component integration; SGDS-specific detail for Vue is `tag.startsWith("sgds-")` to suppress unknown element warnings

When a user reports unexpected component behaviour (wrong event, property not reflecting, slot not rendering), direct them to read the compiled source before trying anything else — see the **Troubleshooting Component Behaviour** section above.

**Global rule — never set explicit widths on SGDS components.** Do not add `width`, `style="width: ..."`, or fixed-width utility classes (e.g. `sgds:w-40`) directly on any `<sgds-*>` element. Width is controlled by the parent layout — use flex, grid, or wrapper divs to constrain it. The only exception is when a user explicitly requests a fixed width.

---

## Available Components

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

---

## Form Input Components

When building forms, use these 9 form input components to capture user data:
1. `<sgds-input>` — text fields
2. `<sgds-textarea>` — multi-line text
3. `<sgds-select>` — dropdown selection
4. `<sgds-checkbox>` / `<sgds-checkbox-group>` — multiple choice
5. `<sgds-radio>` / `<sgds-radio-group>` — single choice
6. `<sgds-combo-box>` — searchable select
7. `<sgds-datepicker>` — date input
8. `<sgds-file-upload>` — file picker
9. `<sgds-quantity-toggle>` — numeric counter

**DO NOT use in forms (these are feedback/state, not input):**
- `<sgds-switch>` — This is a **feedback component** (displays toggle state), not a form input. Use `<sgds-checkbox>` or `<sgds-radio-group>` to collect user choice instead.
- Other non-input components (Alert, Badge, Button, Card, etc.) — These are layout/feedback, not form controls.

For form layout patterns (field pairing, spacing, width constraints, multi-step forms with `<sgds-stepper>`, header hierarchy), see the [sgds-blocks form layout skill](../sgds-blocks/reference/form-layout.md).
| **Feedback** | Alert | [→ reference/alert.md](reference/alert.md) |
| **Feedback** | Spinner | [→ reference/spinner.md](reference/spinner.md) |
| **Feedback** | Skeleton | [→ reference/skeleton.md](reference/skeleton.md) |
| **Feedback** | Progress Bar | [→ reference/progress-bar.md](reference/progress-bar.md) |
| **Feedback** | Toast | [→ reference/toast.md](reference/toast.md) |
| **Feedback** | System Banner | [→ reference/system-banner.md](reference/system-banner.md) |