After working on a Typescript diagram format I wanted to focus on a React equivalent.
Diagrams can be useful for various purposes:
- Quickly sketching ideas with pen & paper or a diagramming too such as Draw.io
- Designing a solution at a high-level before writing any code
- Comparing different designs with eachother to decide which one is best
- Understanding an existing code-base by diagramming it
- Working out a refactoring strategy
In this article I'll describe a UML-influenced diagramming format for React.
Overview
The format consistent of the following elements:
- Component - rectangle with title and list of props
- Component call - caller to callee connected with solid-arrow-terminated line
- Component call with props - caller to props and props to callee connected with solid-arrow-terminated line
- Component render props - render prop rectangle connected to component with dot-terminated line
- Function - rectangle with title and list of parameters
- Type or interface - rectangle with title and list of props
Component
A component is depicted with a depicted with a rectangle with <<Component>> descriptor and title at the top and, optionally, props underneath.
Component call
A component can render another component – here this is referred to as a "component call".
A component call is depicted with a line from the caller component rectangle to the callee component rectangle, terminating in a filled arrow symbol.
Component call with props
A component can pass props to another component – here this is referred to as a "component call with props".
A component call with props is depicted with a line from the caller component rectangle to a props rectangle and another line from the props rectangle to the callee component rectangle, terminating in a filled arrow symbol.
The props are depicted in a props rectangle, in which each prop has its own rectangle. This allows any individual prop to be linked to a type, function or component rectangle.
Component render props
Render props are props for which we pass a React component, a function which renders a component or a React node.
A render prop is depicted with a line from the prop box to a Component or Function rectangle, terminating in a dot symbol.
Function
Same as in the Typescript diagram format, a function is depicted with a rectangle with <<Function>> descriptor and title at the top and, optionally, parameters underneath.
Type or interface
Same as in the Typescript diagram format, a type or interface is depicted with a rectangle with <<Type>> or <<Interface>> descriptor and title at the top and, optionally, fields underneath.
A composition relationship between types or an inheritance relationship between interfaces is depicted with a line from the composer/inheritor to the composed/inherited type/interface, terminating in an empty arrow symbol.
A reference relationship between two components, functions, types or interfaces is depicted with a line from the referencer to the referenced, terminating in an arrow symbol.
Example: contacts list
Here's an example of a React diagram depicting components that make up a contacts list.
- ContactsList component
- ContactsList -> ContactListItem component call with render props
- ContactsListItem component
- ContactPhone component
- ContactEmail component
- Contact interface
- getContacts function
Downloads
To make it easier to use this format, I've implemented downloadable templates for common diagramming tools:
- Mermaid • Download: diagramming-react.mermaid.md
- Draw.io • Download: diagramming-react.drawio
- Figma • Download: diagramming-react.fig
Top comments (3)
An other question. We know react components are functions. And the function vs class is Functions do specific things, Classes are specific things. However this is not true for UI interface elements which are our react components. These components are true objects, ui objects. And it is true the defining component function can have nested functions and a STATE. And we can replicate this component where we want inside our app. This implies the component has all the characteristic of an object, with its properties and its methods. So why, cannot we use diagrammatically the uml class to draw a component ?
All very useful. But i don't understand one thing, where in the diagram is the STATE of the component ? Thank you very much.
Good question!
This article focusses on depicting the structure of your React code (what it's made of), as opposed to its state (how it behaves at runtime). But I'd argue the state is just as important, if not more important.
As mentioned in the article, the diagramming is inspired by a UML diagram type known as the Class Diagram, which is a kind of Structural UML Diagram. This kind of diagram depicts the static or structural elements of the code.
For the state of the application, perhaps we could use a different UML diagram type – the State Machine Diagram. It could be customised as needed to apply to aspects of React, such as component lifecycle points and browser events.
Someone (myself, or maybe you if you like!) should definitely write a follow-up article to address the topic of state diagrams for React.