Unexpected value order with useTransition

[denis-sokolov]

The order of returned values in useTransition is opposite to what I consider to be an established pattern of [value, function].

Current: const [startTransition, isPending] = useTransition().
Expected: const [isPending, startTransition] = useTransition().
Also fine: const { startTransition, isPending } = useTransition().

Rationale

The order is in my opinion inconsistent with other hooks, built-in and community hooks, and this inconsistency is somewhat bothersome on the aesthetic level.

Users without tooling support (TypeScript et al) will see Uncaught TypeError: startTransition is not a function error whenever they get the order wrong.

Having this insonsistency risks reducing the strength of the convention in the community, making hooks less convenient to use overall.

Built-in hooks

const [state, setState] = useState();
const [state, dispatch] = useReducer();
const [startTransition, isPending] = useTransition();

Community examples

I have done a quick overview of positional returned values from hooks in the community. Hooks that use [value, function] pattern:

useImmer, streamich/react-use (useTimeout, useSessionStorage, useLockBodyScroll, useLocalStorage, useToggle) bdbch/react-localstorage, rehooks/local-storage, react-rekindle/use-request.

Hooks that use [function, value] pattern: none.

Is second value optional?

One could argue that, unlike with other examples, useTransition does not require the user to care about the isPending value. However, not using isPending creates a poor UX that the extisting React docs explicitly call out as a problem. We’re supposed to care about isPending. (docs).

Besides, even with corrected value order, the user can still ignore isPending at a low cost of an explicit parameter skip (const [, startTransition] = useTransition()).

Can we return an object?

useState returns a list for convenient aliasing:

const [color, setColor] = useState();
const [position, setPosition] = useState();

For hooks that a single component uses only once the benefit is significantly reduced and the community often chooses to return an object with named values instead. This removes the problem of getting positioned values incorrectly and is more inline with the broader JavaScript ecosystem.

I am speculating here, but it seems like a component will often only have one transition, like the Button example in the docs. In that case it seems beneficial to return named values and reserve the positioned return values for cases where it really matters.

[aweary]

I think it’s risky to have a convention for ordering that’s based on the types of the returned values. The rationale for useTransition’s ordering, as I understand it, is that it returns the most useful thing first. You’ll always want to use startTransition when using useTransition, but the same might not be true for isPending.

I think the other hook APIs already follow this convention, which just so happens to put the function value (setState, dispatch) second. But that’s just because the state is the more useful value.

[denis-sokolov]

I find the convention to put the most important thing first unhelpful. I, personally, don’t feel the intuition whether state or setState is more important, or whether state or dispatch is more important. I need both, neither makes sense without the other. Thus the convention based on importance fails at the only thing it needs to tell me – what is the value order.

[denis-sokolov]

Perhaps the difference in our interpretation of the importance of values as well as preference for different conventions can highlight the need to avoid position values except for the most important cases.

[gaearon]

#20976