Typing Props

Recipe

Define clear, type-safe prop contracts for your React components using TypeScript interfaces and type aliases. Cover required props, optional props, children, and common prop patterns.

Working Example

// Basic props with required and optional fields
type ButtonProps = {
  label: string;
  variant?: "primary" | "secondary" | "danger";
  disabled?: boolean;
  onClick: () => void;
};
 
export function Button({ label, variant = "primary", disabled = false, onClick }: ButtonProps) {
  return (
    <button className={`btn btn-${variant}`} disabled={disabled} onClick={onClick}>
      {label}
    </button>
  );
}

// Typing children
type CardProps = {
  title: string;
  children: React.ReactNode;
};
 
export function Card({ title, children }: CardProps) {
  return (
    <div className="card">
      <h2>{title}</h2>
      <div className="card-body">{children}</div>
    </div>
  );
}

// Render prop pattern
type DataListProps<T> = {
  items: T[];
  renderItem: (item: T, index: number) => React.ReactNode;
};
 
export function DataList<T>({ items, renderItem }: DataListProps<T>) {
  return <ul>{items.map((item, i) => <li key={i}>{renderItem(item, i)}</li>)}</ul>;
}

// Usage
<Button label="Submit" onClick={() => console.log("clicked")} />
<Card title="Welcome"><p>Hello world</p></Card>
<DataList items={["a", "b"]} renderItem={(item) => <span>{item}</span>} />

Deep Dive

How It Works

• Props types act as a contract between the component and its consumers. TypeScript enforces that every required prop is supplied and every value matches the expected type.
• React.ReactNode is the broadest children type. It accepts strings, numbers, JSX elements, arrays, fragments, null, and undefined.
• React.ReactElement is narrower than ReactNode. Use it when you specifically need a JSX element (not a string or number).
• Default values in destructuring (e.g., variant = "primary") work seamlessly with optional props. TypeScript infers the narrowed type inside the function body.
• Union literal types like "primary" | "secondary" give you autocomplete and catch typos at compile time.

Variations

Extending HTML element props:

type InputProps = React.ComponentPropsWithoutRef<"input"> & {
  label: string;
  error?: string;
};
 
export function Input({ label, error, ...rest }: InputProps) {
  return (
    <div>
      <label>{label}</label>
      <input {...rest} />
      {error && <span className="error">{error}</span>}
    </div>
  );
}

Props with component injection:

type LayoutProps = {
  as?: React.ElementType;
  children: React.ReactNode;
  className?: string;
};
 
export function Layout({ as: Component = "div", children, className }: LayoutProps) {
  return <Component className={className}>{children}</Component>;
}

TypeScript Notes

• Use type for props that use unions or intersections. Use interface when you need extends or want declaration merging.
• React.PropsWithChildren<T> is a shorthand that adds children?: React.ReactNode to your type.
• React.ComponentPropsWithRef<"div"> includes the ref prop; ComponentPropsWithoutRef<"div"> excludes it.

Gotchas

• Using React.FC adds an implicit children prop in older React types (pre-18). In React 18+ types, React.FC no longer includes children implicitly.
• Typing children as JSX.Element will reject strings, numbers, and arrays. Use React.ReactNode unless you have a specific reason.
• Spreading ...rest onto a DOM element without filtering custom props causes React warnings about unknown DOM attributes.
• Forgetting to export your props type makes it impossible for consumers to reuse or extend it.

Alternatives

FAQs

type InputProps = React.ComponentPropsWithoutRef<"input"> & {
  label: string;
  error?: string;
};
 
function Input({ label, error, ...rest }: InputProps) {
  return (
    <div>
      <label>{label}</label>
      <input {...rest} />
      {error && <span>{error}</span>}
    </div>
  );
}

type ButtonProps = {
  variant?: "primary" | "secondary";
};
 
function Button({ variant = "primary" }: ButtonProps) {
  // TypeScript narrows variant to "primary" | "secondary" (not undefined)
}

type DataListProps<T> = {
  items: T[];
  renderItem: (item: T, index: number) => React.ReactNode;
};

type LayoutProps = {
  as?: React.ElementType;
  children: React.ReactNode;
};
 
function Layout({ as: Component = "div", children }: LayoutProps) {
  return <Component>{children}</Component>;
}

Related

• TypeScript Basics
• Typing Events
• Generics
• Discriminated Unions