DEV Community: Dan Hammer

An intro to the useComponent pattern

Dan Hammer — Wed, 14 Apr 2021 21:17:06 +0000

You might be familiar with the "useComponent" pattern. I was first introduced to it by this fantastic write-up by Andrew Petersen.

I have found this pattern to be useful in many cases, and thought a basic introduction might be helpful. In this post, I will briefly break down the below simple example of this pattern:

import React, { useState } from "react";

const useRadioButtons = ({ options = [], onChange = () => {}} = {}) => {
  const [selectedOption, setSelectedOption] = useState(options[0]);

  const onChangeOption = (event) => {
    setSelectedOption(event.target.value);
    onChange(event.target.value);
  };

  return {
    props: {
      options,
      onChangeOption,
      selectedOption,
    },
    RadioButtons,
    selectedOption,
  };
};

const RadioButtons = ({ options, onChangeOption, selectedOption }) => {
  return (
    <div>
      {options.map((option) => (
        <>
          <input
            checked={selectedOption === option}
            onChange={onChangeOption}
            type="radio"
            value={option}
          />
          {option}
        </>
      ))}
    </div>
  );
};

export default useRadioButtons;

import React from "react";

import useRadioButtons from "./use-radio-buttons";

function Foo() {
  const { props, RadioButtons, selectedOption } = useRadioButtons({
    options: [`A`, `B`, `C`],
  });

  return (
    <>
      <RadioButtons {...props} />
      {selectedOption}
    </>
  );
}

export default Foo;

What is it?

The RadioButtons component itself is fairly simple. It accepts an array of options, an onChange function, and the current value and returns radio buttons with all of the options.

useRadioButtons, on the other hand, is where things get interesting.

The purpose of this pattern is to contain all of the state, function that rely on state, and hooks (especially any useEffects that specifically belong to the component) so that it's not necessary to set all of it up in the parent.

useRadioButtons sets up the useState for the selectedOption and the onChangeOption function. It returns a props object that can be passed directly into RadioButtons as well as the selectedOption to be used by the parent, and the RadioButtons function.

Less plumbing in the parent

const { props, RadioButtons, selectedOption } = useRadioButtons({
    options: [`A`, `B`, `C`],
  });
...

<RadioButtons {...props}/>

Instead of declaring all of the state inside every parent where this simple RadioButton component is needed, it's possible to just call useRadioButtons once to set it all up. Reading the parent makes it very clear exactly what belongs to the RadioButtons component and exactly what is returned by it, selectedOption. We could contain all of the state in the parent, but sometimes we just want whatever value a component is meant to give us.

Passing functions into the hook

This pattern also gives ample opportunity to create whatever parent-child relationships you need.

For one, you may have noticed that I pass in an optional onChange function. This is most useful if you need to trigger some specific function on change, but we can have fun with it and just throw an alert (don't do this).

  const { props, RadioButtons, selectedOption } = useRadioButtons({
    options: [`A`, `B`, `C`],
    onChange: (selectedOption) => alert(selectedOption),
  });

Getting functions out of the hook

What about calling a function from the parent to change something within the hook? You could use useImperativeHandle (which I have a post on), or you can set up the function and return it.

const useRadioButtons = ({ options = [], onChange = () => {}} = {}) => {
  ....
  const reset = () => {
    setSelectedOption(options[0]);
  };

  return {
    props: {
      options,
      onChangeOption,
      selectedOption,
    },
    RadioButtons,
    selectedOption,
    reset,
  };
};

function Foo() {
  const { props, RadioButtons, selectedOption, reset } = useRadioButtons({
    options: [`A`, `B`, `C`],
    onChange: (selectedOption) => alert(selectedOption),
  });

  return (
    <>
      <RadioButtons {...props} />
      <button onClick={() => reset()}>Reset</button>
      {selectedOption}
    </>
  );
}

This provides a function to reset the options to the first option (bound to a button in this example). As a bonus, this function will always refer to the correct instance of the component. No need to worry about passing around refs.

Don't do this one thing!

Don't return an instance of the component.

import React, { useState } from "react";

const useRadioButtons = ({ options = {}, onChange = () => {}} = {}) => {
  const [selectedOption, setSelectedOption] = useState(options[0]);

  const onChangeOption = (event) => {
    setSelectedOption(event.target.value);
    onChange(event.target.value);
  };

  return {
    RadioButtons: () => (
      <RadioButtons
        {...{
          options,
          onChangeOption,
          selectedOption,
        }}
      />
    ),
    selectedOption,
  };
};

function Foo() {
  const { RadioButtons, selectedOption } = useRadioButtons({
    options: [`A`, `B`, `C`],
  });

  return (
    <>
      <RadioButtons />
      {selectedOption}
    </>
  );
}

This will work and it looks nice, but you will re-create RadioButtons every render. Not only might this cause performance issues, but it will cause you quite a lot of headache if you put more complex state and hooks into useRadioButtons.

You can wrap it in a useCallback and mostly get a stable instance, but do it at your own risk. If you return the props and spread them into the component, you'll only re-render when you expect to. It's worth it for the peace of mind and doesn't add any lines of code to do so.

    RadioButtons: useCallback(() => (
      <RadioButtons
        {...{
          options,
          onChangeOption,
          selectedOption,
        }}
      />
    )),

Conclusion

Next time you want a smart, re-usable component, consider employing this pattern and see if you can even improve it. It's not a one-size-fits-all solution, but there are use cases where it might make your life just a bit easier. I hope this brief introduction has been useful!

In future posts, I'll discuss setting up many instances with different options with a hook, I'll get into the weeds of some issues you might run into, and I'll compare this to other methods of making components do what you want them to do.

Creating A Pdf Saver And Print Previewer in React using useImperativeHandle and jspdf

Dan Hammer — Wed, 14 Apr 2021 19:11:54 +0000

I recently had need to create documents in a React app with a scrolling previewer and the ability to print or save to PDF. Creating a component that could hold and display multi page documents and make them printable and able to be captured as a pdf. This came with some interesting opportunities to make smart components that can handle some work themselves.

I'll go into further detail in the following sections, but for a quick breakdown:

App creates an array of documents with a title and an array of pages made up of react components and a ref for each document.
PrintDocumentScroller creates a scrolling view for all documents and renders a PrintDocument for each and passes the ref down.
PrintDocument creates a PrintArea for each page and exposes a function to generate a PDF of the entire document. This is referenced in App using the ref that was passed down and useImperativeHandle.
PrintArea renders the content in a page-like view so that the preview, print, and pdf all look the same.

Background

refs and useRef

useRef returns a mutable ref object whose .current property is initialized to the passed argument (initialValue). The returned object will persist for the full lifetime of the component

You might be familiar with refs primarily as a way to access the DOM. If you pass a ref object to React with
, React will set its .current property to the corresponding DOM node whenever that node changes.

refs are very useful to maintain a stable reference to any value (but especially DOM nodes or components) for the entire life of a component.

For this project, we will use refs to give access to functions on child components in order to render a canvas of each component.

useImperativeHandle

What is useImperativeHandle?

useImperativeHandle customizes the instance value that is exposed to parent components when using ref. As always, imperative code using refs should be avoided in most cases. useImperativeHandle should be used with forwardRef:
function FancyInput(props, ref) {
  const inputRef = useRef();
  useImperativeHandle(ref, () => ({
    focus: () => {
      inputRef.current.focus();
    }
  }));
  return <input ref={inputRef} ... />;
}
FancyInput = forwardRef(FancyInput);```

Make components do some work!

PrintArea

const PrintArea = forwardRef(({ children, pageIndicator }, ref) => {
  const useStyles = makeStyles(() => ({
    ...
  }));

  const classes = useStyles();

  const pageRef = useRef();

  useImperativeHandle(ref, () => ({
    captureCanvas: () => html2canvas(pageRef.current, { scale: 2 })
  }));

  return (
    <Box className={classes.printArea} ref={pageRef}>
      {children}
      <Box className={classes.pageIndicator}>{pageIndicator}</Box>
    </Box>
  );
});

Above, we create a PrintArea component that will hold each individual page. It applies some styles to show an 11" x 8.5" box with a page number indicator in the bottom right. This component is fairly simple, but it provides us with a function, captureCanvas, to get the canvas just for that specific page.

Each PrintArea component is passed a ref. forwardRef allows us to take the assigned ref and use it inside the component.

useImperativeHandle allows us to assign a series of functions to any ref. In this case, the ref passed down through forward ref. We create captureCanvas, a function to digest the page into a canvas directly. This can be called by any parent component with access to the ref with ref.current.captureCanvas(). This is what we'll take advantage of to gather all of our canvases.

PrintDocument

Each PrintArea is a single page. PrintDocument represents an entire document and all of its pages.

const PrintDocument = forwardRef(({ pages, title }, ref) => {
  const numPages = pages.length;
  const printAreaRefs = useRef([...Array(numPages)].map(() => createRef()));

  useImperativeHandle(ref, () => ({
    generatePDF: () =>
      ...
      })
  }));

  return (
      <div>
        {pages.map((content, index) => (
          <PrintArea
            key={`${title}-${index}`}
            pageIndicator={`${title} - ${index + 1}/${numPages}`}
            ref={printAreaRefs.current[index]}
          >
            {content}
          </PrintArea>
        ))}
      </div>
  );
});

PrintDocument creates a ref for each page and then renders the content within PrintAreas that are passed the correct ref.

PrintDocument also employs useImperativeRef to give its parent access to generate a PDF.

  useImperativeHandle(ref, () => ({
    generatePDF: () =>
      Promise.all(
        printAreaRefs.current.map((ref) => ref.current.captureCanvas())
      ).then((canvases) => {
        const pdf = new jsPDF(`portrait`, `in`, `letter`, true);

        const height = LETTER_PAPER.INCHES.height;
        const width = LETTER_PAPER.INCHES.width;

        // Loop over the canvases and add them as new numPages
        canvases.map((canvas, index) => {
          if (index > 0) {
            pdf.addPage();
          }

          const imgData = canvas.toDataURL(`image/png`);
          pdf.addImage(imgData, `PNG`, 0, 0, width, height, undefined, `FAST`);
        });

        return { pdf, title };
      })
  }));

Because it assigns captureCanvas to each ref passed to a PrintArea, it is able to get the canvas for each page and pass it onto jspdf. Then, it returns the generated pdf and title to a parent component.

savePDFs

const savePDFs = (refs) =>
  Promise.all(
    refs.current.map((ref) => ref.current.generatePDF())
  ).then((pdfs) => pdfs.map(({ title, pdf }) => pdf.save(`${title}.pdf`)));

savePDFs is passed the array of document refs and is able to call generatePDF() on each document and then save it.

In my use case, I gather all of the pdfs and upload them each to S3, which I may cover in a future post.

And now, a warning

From the React docs: As always, imperative code using refs should be avoided in most cases.

It is of course possible to approach this without using refs and useImperativeRef.

We can assign an id to every page and programmatically grab it

documents = [
  {
    title: `Document1`,
    pages: [
      <div id="page-1-1">stuff</div>
      ...
    ]
  },
]

...

pages.map((_, index) =>
  html2canvas(
    document.body.appendChild(
      document.getElementById(
        `page-${documentIndex}-${pageIndex}`
      )
    )
  )
)
...

We can even make this work with some of the styling. I am not a fan of this approach as it makes it slightly more difficult to generate an arbitrary number of pages and is honestly not very readable, but it is completely valid and will work. I chose not to do this in favor of a more readable and adaptable solution.