Complete Guide to Default Props in React TypeScript Components

The Importance of Default Properties in React TypeScript

Setting default values for component properties is a common requirement in React application development. When using TypeScript, this straightforward task becomes complex because it requires considering both runtime behavior and type safety. Many developers encounter type errors on their first attempt, even when the code works correctly at runtime.

Default Property Solutions for Class Components

TypeScript 3.0 and Later Versions

TypeScript 3.0 introduced native support for defaultProps, enabling type checking to work as expected. The key point is that properties should not be marked as optional, even if they are not required in JSX.

interface PageProps {
  foo: string;
  bar: string;
}

export class PageComponent extends React.Component<PageProps, {}> {
    public static defaultProps = {
        foo: "default"
    };

    public render(): JSX.Element {
        return (
            <span>Hello, { this.props.foo.toUpperCase() }</span>
        );
    }
}

This implementation allows rendering the component without passing the foo property:

<PageComponent bar={"hello"} />

It's important to note that the type of defaultProps is automatically inferred, and the compiler uses this information to determine which JSX attributes are required. This approach requires @types/react version 16.4.11 or later.

TypeScript 2.1 to 3.0 Versions

Before TypeScript 3.0, although defaultProps worked completely at runtime, the type system couldn't understand its semantics. Therefore, properties with default values had to be marked as optional.

interface PageProps {
    foo?: string;
    bar: number;
}

export class PageComponent extends React.Component<PageProps, {}> {
    public static defaultProps: Partial<PageProps> = {
        foo: "default"
    };

    public render(): JSX.Element {
        return (
            <span>Hello, world</span>
        );
    }
}

Using the Partial<PageProps> type annotation ensures that defaultProps matches the property interface type while avoiding providing meaningless default values for required properties. When strictNullChecks is enabled, additional null checks or non-null assertions are needed to handle possible undefined values.

Versions Before TypeScript 2.1

In earlier versions, the implementation was similar, but due to the lack of the Partial type, explicit type annotations had to be omitted or default values provided for all properties.

Default Property Strategies for Functional Components

Functional components also support defaultProps, but the component type must be specified as the FunctionComponent interface.

interface PageProps {
  foo?: string;
  bar: number;
}

const PageComponent: FunctionComponent<PageProps> = (props) => {
  return (
    <span>Hello, {props.foo}, {props.bar}</span>
  );
};

PageComponent.defaultProps = {
  foo: "default"
};

Another more concise approach is to use parameter destructuring with default values:

const PageComponent: FunctionComponent<PageProps> = ({foo = "default", bar}) => {
  return (
    <span>Hello, {foo}, {bar}</span>
  );
};

This method completely avoids using defaultProps. It's important to note that if both defaultProps and parameter default values are used, React will prioritize the values from defaultProps.

Advanced Considerations for Type Safety

In real projects, ensuring type safety for default properties is crucial. A common pitfall is marking properties with default values as optional in the interface, which requires handling possible undefined values throughout the component.

Custom utility types can create safer implementations:

type AllPropsRequired<T> = {
  [P in keyof T]-?: T[P];
};

interface Props {
  requiredString: string;
  optionalNumber?: number;
}

const MyComponent: FunctionComponent<Props> = (props) => {
  const args: AllPropsRequired<Props> = {
    ...props,
    optionalNumber: props.optionalNumber ?? 42
  };
  
  return <div>{args.optionalNumber.toFixed(2)}</div>;
};

This approach ensures that within the component, all properties have definite values and correct types, avoiding unnecessary null checks.

Best Practices in Practical Development

The choice of method depends on project requirements and team preferences. For new projects, it's recommended to use TypeScript 3.0+'s native defaultProps support or parameter destructuring in functional components. For maintaining existing codebases, it may be necessary to choose an appropriate strategy based on the current TypeScript version.

Regardless of the chosen method, maintaining consistency is key. Establishing unified default property handling standards within a team can significantly improve code maintainability and development efficiency.