Purpose

Write type-safe React components using TypeScript: discriminated union props, generic components, forwardRef, and proper event typing.

When to use this skill

• typing component props with discriminated unions for variant patterns
• creating generic reusable components (

  <List<T>>

  ,

  <Select<T>>

  )
• forwarding refs with

  forwardRef

  and proper generic typing
• fixing TypeScript errors in React components or hooks

Do not use this skill when

• working with Next.js App Router specifics — prefer

  nextjs-app-router

• designing state architecture — prefer

  state-management

• building forms — prefer

  forms-validation

Procedure

1. Define props as types — use

   type

   (not

   interface

   ) for component props. Export for reuse.
2. Use discriminated unions — for variant props:

   type Props = { variant: 'primary'; icon: ReactNode } | { variant: 'ghost' }

   .
3. Make generic components —

   function List<T>({ items, renderItem }: { items: T[]; renderItem: (item: T) => ReactNode })

   .
4. Forward refs correctly — use

   forwardRef<HTMLDivElement, Props>()

   . Add

   displayName

   for DevTools.
5. Type events —

   onClick: (e: React.MouseEvent<HTMLButtonElement>) => void

   . Use

   React.ChangeEvent<HTMLInputElement>

   for inputs.
6. Type hooks —

   useState<User | null>(null)

   ,

   useRef<HTMLDivElement>(null)

   . Avoid

   any

   .
7. Use

   ComponentPropsWithoutRef

   — extend native element props:

   type Props = ComponentPropsWithoutRef<'button'> & { variant: string }

   .
8. Extract shared types — put reusable types in

   types.ts

   . Co-locate component-specific types with the component.

Discriminated unions

type ButtonProps =
  | { variant: 'primary'; loading?: boolean; onClick: () => void }
  | { variant: 'link'; href: string }
  | { variant: 'icon'; icon: ReactNode; 'aria-label': string; onClick: () => void };

function Button(props: ButtonProps) {
  switch (props.variant) {
    case 'primary':
      return <button onClick={props.onClick} disabled={props.loading}>Submit</button>;
    case 'link':
      return <a href={props.href}>Link</a>;
    case 'icon':
      return <button onClick={props.onClick} aria-label={props['aria-label']}>{props.icon}</button>;
  }
}

Generic components

type ListProps<T> = {
  items: T[];
  renderItem: (item: T) => ReactNode;
  keyExtractor: (item: T) => string;
};

function List<T>({ items, renderItem, keyExtractor }: ListProps<T>) {
  return <ul>{items.map(item => <li key={keyExtractor(item)}>{renderItem(item)}</li>)}</ul>;
}

// Usage — T is inferred
<List items={users} renderItem={u => <span>{u.name}</span>} keyExtractor={u => u.id} />

forwardRef pattern

type InputProps = ComponentPropsWithoutRef<'input'> & { label: string };

const Input = forwardRef<HTMLInputElement, InputProps>(({ label, ...props }, ref) => (
  <div>
    <label>{label}</label>
    <input ref={ref} {...props} />
  </div>
));
Input.displayName = 'Input';

Decision rules

• type

  over

  interface

  for props — unions require

  type

  ; consistency matters.
• Never use

  React.FC

  — it adds implicit

  children

  and breaks generics.
• Discriminated unions over optional booleans —

  variant: 'loading'

  not

  isLoading?: boolean

  .

• ComponentPropsWithoutRef

  to extend native props — avoids ref conflicts.
• Keep

  children

  explicit —

  { children: ReactNode }

  not implicit.

References

• https://react.dev/learn/typescript
• https://www.typescriptlang.org/docs/handbook/2/narrowing.html

Related skills

• nextjs-app-router

  — Next.js-specific patterns

• state-management

  — typed state management

• forms-validation

  — typed form patterns