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 componentsfn-1^{[1]Jump to footnote} 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

This is the implicit prop contract that I'm referring to, and it's not even specific to React but to any pure functionfn-2^{[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:

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" />

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

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"
/>

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:

Related Posts