• Home
  • Blog
  • Projects
  • Bookshelf
  • About
← Back to all posts

Don't Break the Implicit Prop Contract

Published ....
Last modified ....

Share this post on BlueskySee discussion on Bluesky

There's a "secret" implicit prop contract that comes along with all React components, and in fact with most "pure functions" and their arguments! Most React developers may not realize this contract is there, but they often follow it out of convention anyway. In this post I wanted to dig into this implicit prop contract, and specifically spend some time outlining why you shouldn't break it!

What is this about an implicit prop contract?!?

React components were designed to be pure functions. Many have probably heard or seen the concept of ui = f(state) or "UI as a function of state", it's a great way to conceptualize this expectation that React sets on us as we use it to build our user interfaces. This expectation implies a strict prop contract - specifically:

Changes to the props passed to a component, should reflect changes to the user interface experience

[1]Jump to footnote

This is the implicit prop contract that I'm referring to, and it's not even specific to React but to any pure function[2]Jump to footnote.

Let's look an example; imagine we had a function called square, maybe we don't know the internals or implementation details of the function - it might even look like this:

TypeScript code defining a function that returns the square of a number using a while loop with a comment saying that the code works and it shouldn't be modified

source

What we do know however, is that you pass it a single argument that is a type number, and it will give you back a number.

After trying it out a few times, we get back some results that seem to indicate that it will square the number we pass into the function and return the expected result:

square(1); // === 1
square(2); // === 4
square(3); // === 9
square(4); // === 16

This function is following our implicit prop argument contract we talked about above - if you give it a value it will return the square of that value every single time.

This applies to React components just the same (because they're pure functions also [kinda]), imagine we have a Greeting component that will display a greeting for a provided name:

function Greeting({ name }) {
  return (
    <marquee>
      Hello <blink>{name}</blink>!
    </marquee>
  );
}

This component will reliably render a greeting for any name that we provide!

Ok, but what about breaking the contract?

Going back to our square function, what if we found out that actually for some values it doesn't return the square of the input value? Imagine we call it with 5 and instead of giving us back 25 as we'd normally expect it returns 10:

let result = square(5);
console.log(result);
// 10
// Wait... what?!?!

This breaks our mental model that we had formed around the function - we had thought that it would work as expected for every valid argument that we could provide it, only to find out that it doesn't.

If we had started to adopt this code within a larger system and found out about this unexpected outcome, we'd probably be forced to come in and apply a quick fix:

function actualSquare(n: number): number {
  // workaround to fix WTF-1337
  if (n === 5) {
    return 25;
  }
  return square(n);
}

But we need to be clear - we're not fixing the underlying issue here, we're implementing a workaround to bypass the issue. The square function broke our expected contract and now we need additional complexity within the system to account for that breakage.

What if our Greeting component also had a similar issue, imagine that it only greeted the first name that we rendered with, and any subsequent changes to the name it didn't reflect properly?

<Greeting name="Matt" />

Hello Matt!

// and if we re-render with the following:
<Greeting name="Scott" />

Hello Matt!

Maybe we'd opt to implement a workaround similar to our square function as above, with React we may reach for using keys:

// First render

<Greeting name="Matt" />

// Next render

<Greeting
  name="Scott"
  // Fix WTF-420
  key="some-unique-key"
/>

Hello Scott!

However, as we noted above - this is yet another workaround and isn't fixing the underlying issue!

How do I avoid this issue?

In React, this broken contract commonly comes up with the following cases:

  • Derived state not reflecting changes from props
  • Effects not properly "subscribing to" changing props (props missing from an effect's dependencies array)
  • Caching not properly "subscribing to" changing props (props missing from useCallback or useMemo's dependencies arrays)

However there's a number of other possible footguns as well (e.g. manual escape hatches like useRef). Generally, following the Rules of Hooks will ensure that you don't accidentally break this implicit contract!

While there is nothing explicitly implemented within React itself that will prevent breaking this contract - I'd argue that a majority of developers working within a React codebase implicitly have this assumption about components. So while you could choose to break this contract, you'll eventually find someone that becomes confused as to why the code doesn't do what they'd expect it to do so (even if that individual is you in 6+ months)!

Footnotes:

↩Back to reference

Specifically function components, although classes were meant to operate a similar way they just offered more opportunities to break those expectations.

↩Back to reference

While some may say that React components technically aren't exactly pure functions of state, but for the right perspective of what "state" is, they can be. For example hooks like useState rely on the shared React Dispatcher to store state within - if this is considered part of the "state", then the component can be considered pure.

Tags:

Web DevelopmentTipReact

Loading...

Related Posts

Web Development

Website Redesign v11

....

I've once again updated my personal website, this time powered by my own RSC framework and a custom CMS solution as well!

Onboarding Your New AI Teammate

....

Are we reinventing the wheel when it comes to onboarding new AI agents to a codebase, when we already have primitives available for onboarding humans?

Quick Tip - Theme Aware Images

....

Have you ever found the need to change the image you render on a web page based on the current preferred color scheme of your theme?

Async Class Creation In JavaScript

....

Have you ever wanted to create a class in JavaScript or TypeScript but also have the initialization be async? Here's a quick tip on a pattern that I've used in the past!

Website Redesign v10

....

I recently launched a rewrite and redesign of this personal website, I figured I'd talk a bit about the changes and new features that I added along the way!

Server Side Rendering Compatible CSS Theming

....

A quick tip to implementing CSS theming that's compatible with Server Side Rendered applications!

Podcasting By Hand

....

A brief overview on how we launched The Bikeshed Podcast, including a deep dive in our recording and distribution workflows!

Quick Tip - Specific Local Module Declarations

....

A quick tip outlining how to provide specific TypeScript type definitions for a local module!

On File-System Routing Conventions

....

Some rough thoughts on building a file-system routing based web application

You're Building Software Wrong

....

Slicing software: why vertical is better than horizontal.

Single File Web Apps

....

What if you could author an entire web application in a single file?

Resetting Controlled Components in Forms

....

A quick way to handle resetting internal state in components when a parent form is submitted!

A Quick Look at Import Maps

....

A brief look at Import Maps and package.json#imports to support isomorphic JavaScript applications!

Recommended Tech Talks

....

A collection of tech talks that I regularly re-watch and also recommend to everyone!

Request for a (minimal) RSC Framework

....

Some features and functionality that I'd like within a React Server Component compatible framework.

Bluesky Tips and Tools

....

A (running) collection of Bluesky tips, tools, packages, and other misc things!

The Bookkeeping Pattern

....

A quick look at a small but powerful pattern I've been leveraging as of late!

TSLite

....

A proposal for a minimal variant of TypeScript!

Monorepo Tips and Tricks

....

Sharing a few core recommendations when working within monorepos to make your life easier!

Next.js with Deno v2

....

This is a quick post noting that Next.js should now work with Deno v2!

A Better useSSR Implementation

....

Replace that old useState and useEffect combo for a new and better option!

My Current Dev Setup

....

A quick look at the applications and tools that I (generally) use day to day for web development!

Abstract Your API

....

Proposing a solution for sharing core "business" logic across services!

Tip: Request and Response Headers

....

There's a common gotcha when creating Web Request and Response instances with Headers!

Using Feature Toggles to De-risk Refactors

....

Feature toggles are often underused by most software development teams, and yet offer so much value during not only feature development but also refactors

Hohoro

....

A quick introduction to my new side project, hohoro. An incremental JS/TS library build tool!

Custom Favicon Recipes

....

Two neat tricks for enhancing your site's favicon!

Corporate Sponsored OSS

....

The various risks and pitfalls of open source software run by corporations.

The Library-Docs Monorepo Template

....

A monorepo template for managing a library and documentation together.

Building Better Beacon

....

How we solved an almost show-stopping production bug, and how you can avoid it in your own projects.

Project Deep Dive: Tails

....

A(nother) deep dive into one of my recent side projects; tails - a plain and simple cocktail recipe app.

Churn Anxiety

....

When did semver major changes become so scary?

Service Monitors and Observability

....

Leveraging service monitors properly to improve service observability.

On Adopting CSS-in-JS

....

A brief recap of how Wayfair changed it's CSS approach not once but twice in the span of 5 years!

Project Deep Dive: Microfibre

....

A deep dive into one of my recent side projects; microfibre - a minimal text posting application

Pair Programming

....

Pair programming can be good sometimes - but not all the time

Suspense Plus GraphQL

....

A few thoughts on using Suspense with GraphQL to optimize application data loading

You've Launched, Now What?

....

A few thoughts on what to do after you launch a new project

Taking a Break

....

A few quick thoughts on burn out and taking a break

Managing Complex UI Component State

....

A few thoughts on managing complex UI component state within React

Understanding React 16.3 Updates

....

A quick overview of the new lifecycle methods introduced in React 16.3

CSS in JS

....

A few thoughts and patterns for using styled-jsx or other CSS-in-JS solutions

Redesign v6

....

A few thoughts on the redesign of my personal site, adopting Next.js and deploying via Now

JavaScript Weirdness

....

A few weird things about JavaScript

Calendar

....

Building a calendar web application

Tip

Quick-Tip: Codex Chief of Staff Thread

....

Tip: Secrets for Cloudflare Workers

....

Tip: GitHub Created Date Filtering

....

React

Multi-step Native HTML Forms

....

useInterval

....

Server Side Rendering Compatible CSS Theming

....

A quick tip to implementing CSS theming that's compatible with Server Side Rendered applications!

Roundup Notes in Obsidian with Dataview

....

A quick tip for creating roundup or summary notes based on other notes in Obsidian using the Dataview plugin!

Quick Tip - Theme Aware Images

....

Have you ever found the need to change the image you render on a web page based on the current preferred color scheme of your theme?

Async Class Creation In JavaScript

....

Have you ever wanted to create a class in JavaScript or TypeScript but also have the initialization be async? Here's a quick tip on a pattern that I've used in the past!

Server Side Rendering Compatible CSS Theming

....

A quick tip to implementing CSS theming that's compatible with Server Side Rendered applications!

Replacing Dropbox Capture with Raycast

....

Recently Dropbox announced that it was shutting down the Capture app/service, so I sought out an alternative that provided a similar user experience!

Quick Tip - Specific Local Module Declarations

....

A quick tip outlining how to provide specific TypeScript type definitions for a local module!

Bluesky Tips and Tools

....

A (running) collection of Bluesky tips, tools, packages, and other misc things!

The Bookkeeping Pattern

....

A quick look at a small but powerful pattern I've been leveraging as of late!

A Better useSSR Implementation

....

Replace that old useState and useEffect combo for a new and better option!

Tip: Request and Response Headers

....

There's a common gotcha when creating Web Request and Response instances with Headers!

Exporting Custom Slack Emoji

....

How to easily mass-export your custom slack emoji without API access!

Custom Favicon Recipes

....

Two neat tricks for enhancing your site's favicon!

Fixing Zed's language server

....

Zed language server quick tip; fixing Zed's language server

Resetting Controlled Components in Forms

....

A quick way to handle resetting internal state in components when a parent form is submitted!

Request for a (minimal) RSC Framework

....

Some features and functionality that I'd like within a React Server Component compatible framework.

A Better useSSR Implementation

....

Replace that old useState and useEffect combo for a new and better option!

React Error Boundaries: Revisited

....

Revising my previous blog post on React Error Boundaries and my preferred go-to implementation!

Suspense Plus GraphQL

....

A few thoughts on using Suspense with GraphQL to optimize application data loading

Managing Complex UI Component State

....

A few thoughts on managing complex UI component state within React

Understanding React 16.3 Updates

....

A quick overview of the new lifecycle methods introduced in React 16.3