Custom Hooks: Returning Values and Functions

The Purpose of a return Statement in a Hook

Just like any JavaScript function, a hook uses a return statement to send data back to whatever called it. In the useCounter exercise from our previous lesson, you returned a single value: the count.

// A simplified version of your last exercise
function useCounter() {
  const [count, setCount] = useState(0);

  // ... useEffect logic ...

  return count; // Returning a single value
}

function MyComponent() {
  const count = useCounter(); // The component receives the value
  return <h1>Count: {count}</h1>;
}

This is the simplest pattern, and it's perfect for hooks that provide just one piece of information, like the useOnlineStatus hook from the official React documentation which simply returns a boolean.

However, most of the time, we need more than just one piece of data. We usually need the state and the function(s) to change that state. This is where things get interesting.

Pattern 1: Returning an Array

The most common pattern you'll see is returning an array, which mirrors the behavior of React's built-in useState hook. This pattern typically returns two elements: the current state value and a function to update it.

The main advantage of this pattern is the ease of renaming variables when you destructure them in your component.

Let's watch a video that demonstrates this by building a useLocalStorage hook. This hook will need to return both the value stored in local storage and the function to update that value.

As the video explained, the key points for returning an array are:

• Flexibility in Naming: You can name the destructured variables anything you like. This is why useState is so versatile.

  // The hook returns [value, setValue]
  const [name, setName] = useLocalStorage('name'); 
  const [cartItems, setCartItems] = useLocalStorage('cart');
  

• Order is Critical: The main downside is that the order matters. If the hook returns [value, setValue] and you destructure it as [setValue, value], you'll introduce bugs that can be hard to track down.

This pattern is so common that you'll see it everywhere. Here is a simple visual recap.

Pattern 2: Returning an Object

The second common pattern is to return a JavaScript object. This approach has its own set of trade-offs.

The primary benefit of returning an object is that the order of properties does not matter, and the code becomes more "self-documenting" because you use the property names defined in the hook.

Let's explore this by looking at a useFetch hook, which needs to manage several pieces of state: the fetched data, a loading status, and any potential errors.

To summarize the object pattern:

• Order is Irrelevant: You can destructure properties in any order you want.

  // The hook returns { data, isPending, error }
  const { isPending, data } = useFetch('/api/users');
  

• Explicit Naming: You must use the property names defined in the hook. This can make the code clearer but requires an extra step if you need to rename a variable.

  // Renaming `data` to `blogs` is more verbose
  const { data: blogs, isPending } = useFetch('/api/blogs');
  

The official React documentation also provides an excellent example with a useFormInput hook that returns an object containing the value and onChange props for an input field.

A Hybrid Approach

You don't have to choose strictly between an array and an object. Some developers use a hybrid approach that combines the best of both worlds.

A great example is a useBoolean hook, which manages a true/false state.

This pattern, [value, { handler1, handler2 }], gives you the easy renaming of the array pattern for the primary value, while grouping all the related updater functions into a convenient, clearly-named object.

Your Turn: Enhance the useCounter Hook

Now it's time to put this into practice. Let's take the useCounter hook from our last lesson and make it more powerful.

Your task is to modify the useCounter hook so that it returns not only the count but also functions to increment, decrement, and reset the count.

Starter Code:

// in useCounter.js
import { useState, useEffect } from 'react';

// This is the hook from the last lesson.
// It currently only returns the count.
export function useCounter() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const id = setInterval(() => {
      setCount(c => c + 1);
    }, 1000);
    return () => clearInterval(id);
  }, []);

  return count;
}


// in App.js
import { useCounter } from './useCounter';

export default function Counter() {
  const count = useCounter();

  return (
    <div>
      <h1>Seconds passed: {count}</h1>
      {/* We will add buttons here */}
    </div>
  );
}

Instructions:

1. Modify useCounter.js:

   • The useEffect that automatically increments the count every second is no longer needed. You can remove it.
   • Create three new functions inside your useCounter hook:
     • increment: Should increase the count by 1.
     • decrement: Should decrease the count by 1.
     • reset: Should set the count back to 0.
   • Modify the return statement to return the count and your three new functions. You can choose to return an array or an object—think about the pros and cons we just discussed.

2. Update App.js:

   • Destructure the values and functions returned from your useCounter hook.
   • Add three buttons to the JSX: "Increment", "Decrement", and "Reset".
   • Connect the onClick handler of each button to the corresponding function from your hook.

Your final Counter component should look something like this, allowing the user to control the count manually.

(This is a mock-up of the target UI)

Take your time to implement this. This exercise solidifies everything we've covered about what a custom hook provides back to a component.

Conclusion

Excellent work today! You've moved from simply defining a hook to making it a functional, reusable piece of logic that provides an API for your components.

Key Takeaways:

• A custom hook's return statement is its public API, defining what it provides to components.
• Hooks can return any JavaScript type, but the most common patterns are returning an array or an object for state and its updaters.
• Array [value, setValue]: Great for positional data. Allows easy renaming during destructuring. The order is important.
• Object { value, setValue }: Great for named data. The order doesn't matter, and it's self-documenting. Renaming is more verbose.
• You can choose the pattern that best fits the specific logic of your hook.

Next Up:

We've now built a self-contained, reusable useCounter hook. The final piece of the puzzle is to understand what "reusable" really means. In our next lesson, we will reuse a custom hook across multiple components and see firsthand how React ensures that the logic is shared, but the state is not.