SGDS Components Setup Skill

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

Installation

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

Import the library once at your app entry point:

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:

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:

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:

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):

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:

'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:

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

See the official Next.js integration docs for more detail.

Vue

Vue 3 supports web components natively — no SGDS-specific wrappers exist. Refer to the Vue + web components documentation for configuration. The SGDS-specific filter for suppressing unknown element warnings is tag.startsWith("sgds-").

Angular

Angular supports web components natively via CUSTOMELEMENTSSCHEMA — no SGDS-specific wrappers exist. Refer to the Angular elements documentation 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

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