An Introduction to TypeScript with React

Table of Contents

1. What is TypeScript?
2. Why Use TypeScript with React?
3. Setting Up a React Project with TypeScript
4. Core TypeScript Concepts for React
   • Basic Types
   • Interfaces and Type Aliases
   • Typing Props in Components
   • Functional Components with TypeScript
5. State Management with TypeScript
   • Using useState
   • Using useReducer
6. Handling Events in React with TypeScript
7. Advanced Topics
   • Generics for Reusable Components
   • Utility Types
8. Common Pitfalls and Best Practices
9. Conclusion
10. References

What is TypeScript?

TypeScript (TS) is an open-source programming language developed by Microsoft. It is a superset of JavaScript, meaning all valid JavaScript code is valid TypeScript code. The key addition is static typing—the ability to define types for variables, functions, and objects at compile time.

Unlike JavaScript, which is dynamically typed (types are checked at runtime), TypeScript checks types during development, catching errors before code runs. It compiles down to plain JavaScript, so it works everywhere JavaScript does (browsers, Node.js, etc.).

Why Use TypeScript with React?

React and TypeScript are a powerful combination. Here’s why:

• Early Error Detection: TypeScript flags type mismatches (e.g., passing a string where a number is expected) during development, reducing runtime bugs.
• Improved Tooling: IDEs like VS Code use TypeScript to provide autocompletion, inline documentation, and refactoring tools, speeding up development.
• Self-Documenting Code: Type definitions act as documentation, making it easier for teams to understand component props and function signatures.
• Scalability: As React apps grow, TypeScript’s type safety helps maintain code quality and reduces regressions.

Setting Up a React Project with TypeScript

Let’s create a new React project with TypeScript. We’ll use two popular tools: Create React App (CRA) and Vite (a faster alternative).

Option 1: Using Create React App (CRA)

CRA has built-in support for TypeScript. Run the following command:

npx create-react-app my-ts-react-app --template typescript
cd my-ts-react-app
npm start

This generates a React app with TypeScript configured. Key files include:

• .tsx extensions: For React components with TypeScript (instead of .jsx).
• tsconfig.json: TypeScript configuration file (controls compiler options).

Option 2: Using Vite (Faster Setup)

Vite is a build tool that offers faster development. To create a Vite + React + TypeScript project:

npm create vite@latest my-ts-react-app -- --template react-ts
cd my-ts-react-app
npm install
npm run dev

Understanding tsconfig.json

The tsconfig.json file is critical. Here are key options for React:

{
  "compilerOptions": {
    "target": "ESNext", // Compile to modern JS
    "lib": ["DOM", "DOM.Iterable", "ESNext"], // Libraries to include (DOM for React)
    "jsx": "react-jsx", // Support JSX (React 17+ uses "react-jsx")
    "strict": true, // Enable strict type-checking (recommended)
    "esModuleInterop": true, // Compatibility with CommonJS modules
    "skipLibCheck": true, // Skip type-checking for node_modules
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"] // Files to compile
}

Enable strict: true for maximum type safety (enforces rules like no implicit any).

Core TypeScript Concepts for React

Let’s explore TypeScript features essential for React development.

Basic Types

TypeScript supports all JavaScript types, plus additional ones. Here are the most common:

Interfaces and Type Aliases

Interfaces and type aliases define the shape of objects (e.g., React component props). They are nearly identical, but interfaces can be extended, while type aliases cannot.

Example: Defining Props with an Interface

Use an interface to type component props:

// UserProfile.tsx
import React from 'react';

// Define props interface
interface UserProfileProps {
  name: string; // Required string prop
  age: number; // Required number prop
  isStudent?: boolean; // Optional boolean prop (denoted with "?")
}

// Component using the interface
const UserProfile: React.FC<UserProfileProps> = ({ name, age, isStudent = false }) => {
  return (
    <div>
      <h1>{name}</h1>
      <p>Age: {age}</p>
      {isStudent && <p>Status: Student</p>}
    </div>
  );
};

export default UserProfile;

Here, UserProfileProps enforces that name (string) and age (number) are required, while isStudent is optional (defaults to false).

Type Aliases

Type aliases work similarly but use the type keyword:

type UserProfileProps = {
  name: string;
  age: number;
  isStudent?: boolean;
};

Use interfaces for props (they’re more idiomatic in React) and type aliases for union/types or complex types.

Functional Components with TypeScript

There are two ways to type functional components:

1. Using React.FC (Functional Component)

React.FC is a generic type that defines a functional component with props:

const Greeting: React.FC<{ name: string }> = ({ name }) => {
  return <h1>Hello, {name}!</h1>;
};

Note: React.FC automatically includes children as an optional prop. To disable this, avoid React.FC (see below).

2. Explicitly Typing Props (Recommended)

A more flexible approach is to explicitly type the props parameter:

interface GreetingProps {
  name: string;
  children?: React.ReactNode; // Explicitly allow children
}

const Greeting = ({ name, children }: GreetingProps) => {
  return (
    <div>
      <h1>Hello, {name}!</h1>
      {children}
    </div>
  );
};

This is often preferred because it avoids implicit children and is more flexible.

State Management with TypeScript

React hooks like useState and useReducer work seamlessly with TypeScript. Let’s see how to type them.

Using useState

TypeScript infers state types from the initial value. For simple values, no extra work is needed:

import { useState } from 'react';

const Counter = () => {
  // Type inferred as number (initial value is 0)
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(prev => prev + 1)}>Increment</button>
    </div>
  );
};

Typing Complex State (e.g., Objects)

For objects, TypeScript infers the type from the initial object. If the initial state is null or undefined, explicitly type the state:

interface User {
  name: string;
  email: string;
}

const UserProfile = () => {
  // Explicitly type as User | null (since initial state is null)
  const [user, setUser] = useState<User | null>(null);

  const fetchUser = () => {
    // Simulate API call
    setUser({ name: "Alice", email: "[email protected]" });
  };

  return (
    <div>
      <button onClick={fetchUser}>Load User</button>
      {user && <p>{user.name} ({user.email})</p>}
    </div>
  );
};

Using useReducer

useReducer is useful for complex state logic. Type the state and actions:

import { useReducer } from 'react';

// Define state interface
interface TodoState {
  todos: string[];
  input: string;
}

// Define action types (union type)
type TodoAction = 
  | { type: 'SET_INPUT'; payload: string }
  | { type: 'ADD_TODO' }
  | { type: 'CLEAR_TODOS' };

// Reducer function with typed state and action
const todoReducer = (state: TodoState, action: TodoAction): TodoState => {
  switch (action.type) {
    case 'SET_INPUT':
      return { ...state, input: action.payload };
    case 'ADD_TODO':
      return { ...state, todos: [...state.todos, state.input], input: '' };
    case 'CLEAR_TODOS':
      return { ...state, todos: [] };
    default:
      return state;
  }
};

const TodoApp = () => {
  const [state, dispatch] = useReducer(todoReducer, {
    todos: [],
    input: '',
  });

  return (
    <div>
      <input
        type="text"
        value={state.input}
        onChange={(e) => dispatch({ type: 'SET_INPUT', payload: e.target.value })}
      />
      <button onClick={() => dispatch({ type: 'ADD_TODO' })}>Add Todo</button>
      <button onClick={() => dispatch({ type: 'CLEAR_TODOS' })}>Clear</button>
      <ul>
        {state.todos.map((todo, index) => (
          <li key={index}>{todo}</li>
        ))}
      </ul>
    </div>
  );
};

Handling Events in React with TypeScript

React events (e.g., onClick, onChange) have specific TypeScript types. Use React’s event types (e.g., React.MouseEvent, React.ChangeEvent) for type safety.

Example: Typing onClick

const Button = () => {
  // React.MouseEvent<HTMLButtonElement> for button clicks
  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
    console.log('Button clicked!', e.target);
  };

  return <button onClick={handleClick}>Click Me</button>;
};

Example: Typing onChange for Inputs

const Input = () => {
  const [value, setValue] = useState('');

  // React.ChangeEvent<HTMLInputElement> for input changes
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setValue(e.target.value);
  };

  return <input type="text" value={value} onChange={handleChange} />;
};

Common React event types:

• React.MouseEvent<T>: For mouse events (e.g., onClick, onMouseOver).
• React.ChangeEvent<T>: For input changes (e.g., onChange on inputs, selects).
• React.FormEvent<T>: For form submission (onSubmit).

Advanced Topics

Generics for Reusable Components

Generics let you create components that work with multiple types. For example, a generic List component that renders items of any type:

// Generic interface for List props
interface ListProps<T> {
  items: T[];
  renderItem: (item: T) => React.ReactNode;
}

// Generic List component
const List = <T,>({ items, renderItem }: ListProps<T>) => {
  return (
    <ul>
      {items.map((item, index) => (
        <li key={index}>{renderItem(item)}</li>
      ))}
    </ul>
  );
};

// Usage with strings
<List 
  items={["Apple", "Banana"]} 
  renderItem={(fruit) => <p>{fruit}</p>} 
/>

// Usage with numbers
<List 
  items={[1, 2, 3]} 
  renderItem={(num) => <p>Number: {num}</p>} 
/>

Utility Types

TypeScript provides utility types to transform existing types. Here are useful ones for React:

Partial<T>: Makes all properties of T optional.

Useful for state updates where you might only change a few fields:

interface User {
  name: string;
  age: number;
}

// Partial<User> = { name?: string; age?: number }
const updateUser = (user: User, changes: Partial<User>): User => {
  return { ...user, ...changes };
};

const user: User = { name: "Alice", age: 30 };
const updatedUser = updateUser(user, { age: 31 }); // { name: "Alice", age: 31 }

Pick<T, K>: Selects a subset of properties K from T.

interface User {
  id: number;
  name: string;
  email: string;
}

// Pick only "name" and "email"
type UserNameEmail = Pick<User, "name" | "email">; 
// { name: string; email: string }

Omit<T, K>: Removes properties K from T.

// Omit "id" from User
type UserWithoutId = Omit<User, "id">; 
// { name: string; email: string }

Common Pitfalls and Best Practices

1. Avoid any Type

The any type disables TypeScript’s type checking. Use unknown instead when the type is uncertain, and narrow it down with type guards:

// Bad: Using any
const data: any = "hello";
data.toUpperCase(); // No error, but unsafe

// Good: Using unknown and type guard
const value: unknown = "test";
if (typeof value === "string") {
  value.toUpperCase(); // Safe (TypeScript knows value is a string)
}

2. Enable strict: true in tsconfig.json

strict: true enables strict type-checking rules (e.g., noImplicitAny, strictNullChecks), catching more errors early.

3. Type children Explicitly

If a component accepts children, type it as React.ReactNode (supports all valid React children: elements, strings, fragments, etc.):

interface CardProps {
  children: React.ReactNode; // Accepts any React child
}

const Card = ({ children }: CardProps) => {
  return <div className="card">{children}</div>;
};

4. Handle Optional Props Carefully

Optional props (denoted with ?) can be undefined. Use default values to avoid runtime errors:

interface ButtonProps {
  variant?: "primary" | "secondary"; // Optional union type
}

const Button = ({ variant = "primary" }: ButtonProps) => {
  // variant is guaranteed to be "primary" or "secondary" (no undefined)
  return <button className={`btn-${variant}`}>Click</button>;
};

Conclusion

TypeScript elevates React development by adding static typing, improving tooling, and enhancing scalability. By mastering TypeScript basics (types, interfaces, props), state typing, and advanced concepts like generics, you can build robust, maintainable React applications.

Start small: convert a simple React component to TypeScript, experiment with props and state typing, and gradually adopt advanced features. The investment in TypeScript will pay off as your app grows!

References

• TypeScript Official Documentation
• React + TypeScript Cheatsheets
• React Official TypeScript Guide
• Vite + React + TypeScript Setup
• tsconfig.json Reference