What is a UI component explorer and do you need one in your React project?

Let’s say you’re tasked with implementing a “user details” screen based on a specific design. You inspect it and learn that it consists of a circular user avatar with a border, some text, and two buttons. You then create a component that will wrap the entire view and start to add its elements.

It’s time to add the avatar. But hey, what if one of your colleagues has already created a component that would render a circle filled with a user’s face? Surely, it’s better to reuse it, get the job done faster, and limit the codebase complexity.

Here’s what happens next.

You take a dip into the file structure of your project, looking for a component with “avatar” in its name. There’s nothing like that, but you’ve found one called “UserPhoto.”

Now, is it doing what you need it to?

To find out, you’d normally look at its source and/or check how it looks like in the running application, which includes having to figure out which route to visit and get through potential intermediate steps.

Both of these options take a considerable amount of time. And that’s just for one component, while you may have to evaluate several.

What if there was a better way? A tool that would give you a bird’s eye view on the components at your disposal and let you instantly see what each of them looks like (in all the variations intended by the component original creator). It would accelerate the process of figuring out whether you can use the given component to achieve your goal (possibly adapting it), or it would make more sense to create one from scratch.

Introducing the UI component explorer

A UI component explorer (sometimes also called a styleguide) is a simple auxiliary web application that you can run alongside your actual web application while it’s being developed. You can use it to explore the components created so far during the development.

In practice, it looks more or less like this:

A UI component explorer usually features a searchable list of documented components (visible on the left). When we click on the component’s name, the main part starts to show its:

• description,
• list of accepted props (along with their types and default values),
• example usages.

How to create a UI component explorer? 

There’s a couple of popular tools you can consider for the job. At the time of writing this article, the most popular solutions are Storybook, Docz, and Styleguidist.

Each of these tools is based on a similar principle:

You can add an additional file that will document a component to every component in your project. In the case of Storybook, the file is in JavaScript, while Docz and Styleguidist use a format called MDX, which is a well-known Markdown format that additionally supports React’s JSX syntax. You would usually keep the documentation file in the same folder as other component-related stuff (its source files, test files, style files, etc.).

Next, you run the component explorer build script, which recursively looks through your project’s file structure, searching for all the *.mdx (or *.stories.js in case of Storybook) files. It builds a web application similar to the one on the screenshot above, putting all the content from the documentation files together.

The example of a component explorer I showed you above was built using Docz.

Below, you can see the documentation page of the Alert component again, this time together with the source code with which it was created. The syntax for Styleguidist and (especially) Storybook is different, but the general idea is very similar.

As you can see, it looks like Markdown, but there are a couple of extra elements that wouldn’t be treated in the way you’d want by a traditional Markdown renderer: the imports and the usage of Props and Playground components.

The Props component, showing a nice summary of props accepted by Button, gathers information about them automatically - either from Button’s PropTypes, or TypeScript/Flow type declarations (if we use them instead).

The main course is, however, the Playground component. It renders the JSX provided as its children and additionally displays this JSX like a traditional code block.

What’s more, the source code can be edited in place. You can check how the component works with prop configurations that haven’t been presented in usage examples prepared by the author of the documentation file.

Advantages of UI component explorers

1. Improved component discoverability

A UI component explorer solves the problem I described in the introduction to this article. It doesn’t matter whether you're given the task of creating a component from a visual design or textual specification. You can use the component explorer to minimize the time spent on exploring the UI component library in search of the one that you might reuse.

2. Documentation

The ultimate form of documentation is always the source code itself. However, understanding it deeply enough to use the component correctly takes a lot of time. Seeing the prescribed usage examples in the component explorer allows developers to spend less time on getting to know the component before using it. If analyzing the source code is still necessary, it’s easier when you have already seen how it looks and behaves.

3. Isolated environment for component development

With component explorer, it’s possible to build components while rendering them right on their documentation page. Only after the component is finished, it will be instantiated in its target parts of the app. This different approach leads to creating more reusable components. We’re working on the component out of the context in which it will be used, so it’s more difficult to make context-specific assumptions that usually limit component reusability.

Another benefit is the fact that you can render the component several times, with prop combinations for all use cases you foresee and cycle through them regularly, making sure the changes related to one of the use cases didn’t break how others render.

The cost of a UI component explorer

As usual, the benefits we get from UI component explorer don’t come free of charge.

Writing the documentation file takes extra time during development. Fortunately, many parts of this file can be created automatically (either by copying from previous files and replacing the component name, or using IDE-powered snippet insertion, or, preferably, a file generating script that could be made part of the project repository). The only place where you actually have to put in the effort is the section with usage examples.

Is writing usage examples an acceptable cost of having a component explorer in your project?

This is a question that every team should answer on its own. However, if you’re doing component snapshot unit tests as part of your project workflow, the answer is most likely positive.

The reason is that the code for showing the example usages will usually be identical to the code you have to put into your unit test to render the given component. The tools for building component explorers even offer an option to create the tests automatically based on example usages, either as built-in features or in the form of a plugin.

Do you need to add all of your components to the explorer?

Well, no, you actually don’t have to do that. There’s probably little value in the discoverability of components that are very unlikely to be reused, like those representing entire pages. The components I would document for sure are the ones that have a fair chance of being reused. A good example is a form element or a layout component.

For each component, we can define as many example usages as we want. My rule of thumb is:

If a change of a particular prop value changes the component in a non-obvious way, it deserves an example usage.

Future improvements

There’s one option that I miss when it comes to UI component explorers. It’s creating a very long page that would render all of the usage examples for all the components we have in the system (like Bootstrap used to do with their components). It would make checking whether a component we want already exists in our project really simple. And for me, that’s the primary value of component explorers.

Conclusion

Component explorers are becoming increasingly popular in the component-based section of the frontend development world. They encourage component reuse, make it possible to document your components in an interactive way, and offer you an isolated development environment where you can create your components without interference from the rest of the application.

They add a little overhead of creating the documentation files, but most of it can be reduced by automating the insertion of the repetitive parts. In my opinion, they are well worth using in your upcoming project!