You open a new React project, add TypeScript, and immediately hit Stack Overflow for how to type your first prop. The first answer says use interface. The second says type. The third is a six-paragraph thread about why one is semantically superior to the other. You close the tab and just write any to get on with your life.
Sound familiar? TypeScript in React has a reputation problem. Not because it's hard — it's genuinely great once it clicks — but because the community has generated a staggering volume of contradictory, context-free advice. Every dev tool tutorial starts with TypeScript. Every linting config bans any. Every PR reviewer has a hot take on generics.
This guide cuts through that. I'm not going to cover every TypeScript feature or every React pattern. What I'm going to do is share the specific conventions I use in production React + TypeScript apps in 2025 — the things that have made codebases genuinely easier to work in, not just theoretically safer.
What this guide is NOT
Before we get into it, let me set expectations clearly:
- Not a TypeScript basics tutorial. I'm assuming you know what a type is, what an interface is, and that
string !== String. - Not exhaustive. TypeScript has dozens of utility types, conditional types, template literal types, and more. I'm not covering all of them — just the ones I reach for constantly.
- Not framework-neutral. This is specifically about TypeScript in React apps. Some of these patterns won't apply to a Node.js CLI or a library.
- Not about configuration. Strict mode settings, tsconfig targets, module resolution — another article for another day.
What this guide IS is opinionated. I'm going to tell you what I think the right call is in most situations, and why. You'll disagree with some of it. That's fine.
Typing Props the Right Way
Let's start here because it's where every React + TypeScript journey begins, and where a lot of the confusion lives.
Interface vs. Type Alias
Here's my rule: use interface for component props, type for everything else.
Why? Interfaces have declaration merging, which can occasionally bite you in unexpected ways, but they also produce cleaner error messages and feel more natural for describing object shapes. They're also what the React community defaults to, so your code will look familiar to anyone joining your team.
// Good — interface for component props
interface ButtonProps {
label: string;
onClick: () => void;
variant?: "primary" | "secondary" | "ghost";
disabled?: boolean;
}
// Good — type alias for unions and computed shapes
type ButtonVariant = "primary" | "secondary" | "ghost";
type Theme = "light" | "dark";
You'll see guides that say "always use type" or "always use interface." Honestly? Consistency matters more than which one you pick. Pick a rule and stick to it across your codebase.
Required vs. Optional Props
Default to required. Make something optional only when it genuinely has a sensible default or when it's truly not needed in many use cases.
This is the inverse of what a lot of developers do. They add ? to everything to make TypeScript stop complaining, and then their components have fifteen optional props where most of them are actually always passed. That erases the value of having types at all.
// Bad — over-optionalized
interface CardProps {
title?: string;
description?: string;
imageUrl?: string;
href?: string;
}
// Good — be explicit about what's truly optional
interface CardProps {
title: string;
description: string;
imageUrl?: string; // genuinely optional — card can work without an image
href?: string; // optional — sometimes cards aren't clickable
}
Extending HTML Element Props
This is one of the most useful patterns in React + TypeScript, and it's underused. When you're building a component that wraps an HTML element, extend that element's props so your component accepts all the native attributes automatically.
// Without this pattern — you have to manually add every HTML attribute
interface ButtonProps {
label: string;
onClick: () => void;
// what about type="submit"? aria-label? data-testid? className?
// you'll spend forever adding these one by one
}
// With this pattern — extend React's built-in types
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
label: string;
variant?: "primary" | "secondary";
// ...and you automatically get onClick, type, aria-*, data-*, className, etc.
}
const Button = ({ label, variant = "primary", ...rest }: ButtonProps) => {
return (
<button className={`btn btn-${variant}`} {...rest}>
{label}
</button>
);
};
The ...rest spread pattern combined with extended HTML props is one of those things that once you start using, you can't go back. Your components become instantly more composable and you stop maintaining a manual list of passthrough props.
Custom Hooks with TypeScript
Custom hooks are where TypeScript really earns its keep, because hooks often manage complex state and return multiple values. If your hook's return type is just inferred as any[], you've lost all the benefit.
Typing Return Values Explicitly
Always define the return type of custom hooks explicitly. Don't rely on inference here — it breaks down the moment your hook has multiple return paths or conditional logic.
// Bad — inferred return type is unreliable
function useUser(id: string) {
const [user, setUser] = useState(null); // typed as null
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
// ...fetch logic
return { user, loading, error }; // TypeScript infers this poorly
}
// Good — define the return interface explicitly
interface User {
id: string;
name: string;
email: string;
}
interface UseUserResult {
user: User | null;
loading: boolean;
error: string | null;
}
function useUser(id: string): UseUserResult {
const [user, setUser] = useState<User | null>(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
// ...fetch logic
return { user, loading, error };
}
Now when you destructure this hook in a component, every field is typed correctly, and you get autocomplete without having to remember what the hook returns.
Generics for Reusable Hooks
Okay so here's where hooks get really powerful. If you're building a reusable data-fetching hook, generics let you make it work with any shape of data without losing type safety.
interface FetchResult<T> {
data: T | null;
loading: boolean;
error: string | null;
}
function useFetch<T>(url: string): FetchResult<T> {
const [data, setData] = useState<T | null>(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
useEffect(() => {
let cancelled = false;
fetch(url)
.then((res) => {
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json() as Promise<T>;
})
.then((d) => {
if (!cancelled) {
setData(d);
setLoading(false);
}
})
.catch((err: Error) => {
if (!cancelled) {
setError(err.message);
setLoading(false);
}
});
return () => { cancelled = true; };
}, [url]);
return { data, loading, error };
}
// Usage — TypeScript knows exactly what data is
const { data, loading, error } = useFetch<User>("/api/user/123");
// data is typed as User | null — not unknown, not any
The T propagates through the entire hook. That's the magic. You call useFetch<User> once at the call site, and TypeScript figures out the rest.
Generic Components
Generics in components are the thing that trips up most mid-level React developers. They look intimidating. They have funny angle-bracket syntax. But once you understand when to reach for them, they save you from maintaining three slightly-different versions of the same component.
When to Use Generic Components
Reach for generics when your component works with data of a variable shape, but still needs to be type-safe. A list component, a select dropdown, a data table — these are classic candidates.
// Without generics — you end up with separate UserList, ProjectList, etc.
// or you use any[] and lose type safety
// With generics — one component that works for any data shape
interface ListProps<T> {
items: T[];
renderItem: (item: T, index: number) => React.ReactNode;
keyExtractor: (item: T) => string;
emptyMessage?: string;
}
function List<T>({ items, renderItem, keyExtractor, emptyMessage = "No items" }: ListProps<T>) {
if (items.length === 0) {
return <p className="empty-state">{emptyMessage}</p>;
}
return (
<ul>
{items.map((item, index) => (
<li key={keyExtractor(item)}>
{renderItem(item, index)}
</li>
))}
</ul>
);
}
// Usage — TypeScript infers T from the items array
<List
items={users}
keyExtractor={(u) => u.id} // TypeScript knows u is a User
renderItem={(u) => <UserCard user={u} />}
/>
Notice that you don't even need to write <List<User>> at the call site — TypeScript infers T = User from the items prop. That's inference doing its job.
One thing to watch: in .tsx files, the compiler can confuse <T> with a JSX tag. If you get a parse error, either add a constraint (<T extends object>) or use a comma (<T,>) to disambiguate.
Discriminated Unions for State
Here's the thing that's changed how I think about React state more than anything else: replacing boolean flags with discriminated union types. This single pattern eliminates entire categories of bugs.
The Boolean Flag Problem
You've seen this component. You've written this component.
// The boolean flag trap
interface FormState {
isLoading: boolean;
isSuccess: boolean;
isError: boolean;
errorMessage?: string;
data?: SubmitResult;
}
// Nothing stops you from setting isLoading: true AND isSuccess: true simultaneously
// That's an impossible state — but TypeScript can't catch it
const state: FormState = {
isLoading: true,
isSuccess: true, // ← this should be impossible
isError: false,
};
When you have three booleans representing what should be a single sequential state, you have 2³ = 8 possible combinations, but only 4 of them are actually valid. TypeScript can't protect you from the invalid ones.
The Discriminated Union Fix
// Model the actual states that can exist
type FormState =
| { status: "idle" }
| { status: "loading" }
| { status: "success"; data: SubmitResult }
| { status: "error"; errorMessage: string };
// Now the impossible states are literally unrepresentable
const state: FormState = { status: "idle" };
// And in your component, TypeScript narrows types automatically
function FormFeedback({ state }: { state: FormState }) {
if (state.status === "loading") {
return <Spinner />;
}
if (state.status === "error") {
// TypeScript knows state.errorMessage exists here
return <ErrorBanner message={state.errorMessage} />;
}
if (state.status === "success") {
// TypeScript knows state.data exists here
return <SuccessBanner data={state.data} />;
}
return null; // idle
}
The key is the status discriminant property. When you narrow on state.status === "error", TypeScript automatically knows which variant of the union you're in, and which other fields are available.
This pattern is especially powerful in data-fetching scenarios, form submission flows, and anywhere you have a multi-step process. Start reaching for it instead of isLoading / isError / isSuccess and your state management will become dramatically cleaner.
Taming any
Let me be direct: any is a code smell, but it's not always your fault. Sometimes you're working with a library that has poor types, an API that returns unpredictable shapes, or legacy code you don't own. The goal isn't to never use any — it's to reach for better tools first.
Use unknown Instead of any for External Data
unknown is the type-safe cousin of any. It says "I don't know what this is yet" instead of "pretend this is whatever I need it to be." You can't do anything with an unknown value without first narrowing it with a type guard.
// Bad — any lets you do anything, including wrong things
async function fetchData(url: string): Promise<any> {
const res = await fetch(url);
return res.json();
}
const data = await fetchData("/api/user");
data.doesNotExist.boom; // TypeScript is fine with this. Your app is not.
// Good — unknown forces you to validate before using
async function fetchData(url: string): Promise<unknown> {
const res = await fetch(url);
return res.json();
}
function isUser(value: unknown): value is User {
return (
typeof value === "object" &&
value !== null &&
"id" in value &&
"name" in value &&
typeof (value as User).id === "string"
);
}
const data = await fetchData("/api/user");
if (isUser(data)) {
// TypeScript now knows data is User
console.log(data.name);
}
Type Guards Are Your Friends
The value is User return type in the example above is a type guard. It's a function that tells TypeScript "if this returns true, the value is of type T in the branches that follow." This is how you move from unknown territory into properly typed territory without resorting to any.
// Reusable type guard pattern
function isNonNull<T>(value: T | null | undefined): value is T {
return value !== null && value !== undefined;
}
const items: (User | null)[] = [user1, null, user2, null];
const validUsers = items.filter(isNonNull); // typed as User[], not (User | null)[]
When never Is the Right Answer
never is the type that can't exist. It's useful for exhaustiveness checks — making sure you've handled every case in a union.
type Shape = "circle" | "square" | "triangle";
function getArea(shape: Shape, size: number): number {
switch (shape) {
case "circle":
return Math.PI * size * size;
case "square":
return size * size;
case "triangle":
return (size * size) / 2;
default:
// If you add "hexagon" to the Shape union and forget to handle it here,
// TypeScript will throw a compile error on this line
const _exhaustiveCheck: never = shape;
throw new Error(`Unhandled shape: ${_exhaustiveCheck}`);
}
}
This pattern scales beautifully with discriminated unions. Add a new status to your state type, and every switch statement that wasn't updated will fail at compile time. That's exactly the kind of safety net TypeScript is supposed to provide.
Before vs. After: TypeScript Patterns
Here's a quick-reference table of the common before/after shifts. These are the six patterns I most often see in code review that a bit of TypeScript discipline cleans up immediately.
| Pattern | Without TypeScript Discipline | With TypeScript Discipline |
|---|---|---|
| Prop typing | props: any or no types at all |
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> |
| Optional props | Everything is ? to avoid errors |
Only truly optional fields are optional; defaults handled by destructuring |
| Loading/error state | isLoading: boolean, isError: boolean, isSuccess: boolean |
Discriminated union: { status: "idle" | "loading" | "success" | "error" } |
| External API data | const data: any = await fetch(...).then(r => r.json()) |
const data: unknown + type guard before use |
| Reusable list | Separate UserList, ProjectList components with duplicated logic |
One generic List<T> component with typed renderItem and keyExtractor |
| Hook return type | Inferred — breaks on multiple return paths, confusing autocomplete | Explicit interface UseXxxResult { ... } as the return type annotation |
Module Structure for a TypeScript React Project
Okay, one more thing worth getting right from the start: where files live. A consistent folder structure does more for long-term maintainability than almost any TypeScript pattern. Here's the structure I use and recommend for mid-to-large React + TypeScript apps in 2025.
src/
├── app/ # Next.js App Router pages (or pages/ for older setup)
│ ├── layout.tsx
│ ├── page.tsx
│ └── blog/
│ └── [slug]/
│ └── page.tsx
│
├── components/ # Shared UI components
│ ├── Button/
│ │ ├── Button.tsx # Component
│ │ ├── Button.types.ts # Interface / type exports
│ │ ├── Button.styles.ts# Styled components or CSS module
│ │ └── index.ts # Re-export for clean imports
│ └── List/
│ └── ...
│
├── hooks/ # Custom hooks
│ ├── useFetch.ts
│ ├── useLocalStorage.ts
│ └── useDebounce.ts
│
├── lib/ # Utilities, helpers, non-UI logic
│ ├── api.ts # Fetch wrappers
│ ├── formatters.ts # Date, currency, string helpers
│ └── validators.ts # Type guards and runtime validation
│
├── types/ # Shared TypeScript types
│ ├── api.ts # API response shapes
│ ├── models.ts # Domain model interfaces (User, Post, etc.)
│ └── index.ts # Re-exports
│
├── context/ # React context providers
│ └── ThemeContext.tsx
│
└── styles/ # Global styles, theme tokens
└── globals.css
A few rules I enforce in this structure:
- Co-locate component types. Each component folder has its own
.types.tsfile. Don't dump all types into a single globaltypes.ts— that file becomes a graveyard. - The
types/directory is for shared domain types only. API response shapes, database models, shared interfaces that more than one component needs. Not component-specific props. - Barrel files are useful but dangerous. An
index.tsin each component folder is fine. A single barrel for your entirecomponents/directory will cause circular dependency nightmares in larger apps. - Hooks go in
hooks/, not co-located with components. This is a deliberate choice against the "co-locate everything" philosophy. In my experience, hooks get reused across features, and burying them inside a component folder makes them harder to find and share.
TL;DR
- Use
interfacefor component props,typefor everything else — pick a rule and apply it consistently. Default to required props; only mark things optional when they genuinely are. - Extend HTML element props using
React.ButtonHTMLAttributes<HTMLButtonElement>and friends — this gets you all native attributes for free and makes components composable with...rest. - Always annotate custom hook return types explicitly — define a
UseXxxResultinterface and return it. Don't trust inference when there's conditional logic involved. - Use discriminated unions instead of boolean flags for anything with multiple states —
{ status: "idle" | "loading" | "success" | "error" }is safer, clearer, and catches impossible states at compile time. - Replace
anywithunknownat API boundaries — then validate with type guards before use. Saveneverfor exhaustiveness checks in switch statements. - Structure your modules intentionally — co-locate component types, put shared domain types in
types/, hooks inhooks/, and use barrel files per component folder (not globally).