Inline Documentation and Performance Updates

Hi friends!

It’s been a little quiet on this blog. Rest assured, a lot of interesting and important work is being done within G2! The two major updates include adding support for inline documentation (for supported editors) as well as a bunch of performance optimizations. Both of which are in service of making G2 Components easier to use.

Inline Documentation and Autocompletion

A gif demonstrating how the inline docs can be viewed within VS Code by hovering over G2 components.

All of G2’s (non-experimental) components have received detailed inline documentation and auto code completion. These features are unlocked by using a code editor that supports TypeScript, such as Visual Studio Code (aka. VS Code).

Having inline docs is extremely handy for those who are already familiar with the library. (It’s certainly helped me a bunch!). However, the true potential and impact is lies in familiarizing folks who are brand new to the G2 Components. Folks who have jumped without reading documentation or source code (confession, I’m one of those) and are wondering to themselves…

“What on earth is an HStack?”

With the recent updates, the docs and code examples for G2 Components are just a “hover” or “click” away. Not only that, but every single of the component’s properties have also been documented!

Other parts of the project have also received typing treatment, most notably G2’s Variable system (a sub-system of the Styling System). I plan on writing about this in the near future (stay tuned!).

A Word on TypeScript

I’ll start off by saying… I am not a TypeScript expert. I understand the basics and know enough to clobber together some mildly advanced (and ridiculous looking) type definitions. Another way to put it is… I love the features of TypeScript, but I prefer writing JavaScript.

With that being said… a question we can ask is:

“Should G2 Components be written in TypeScript?”

In my opinion, no (at least, not in the short/medium term). The reason is because not too many folks are familiar with advanced TypeScript (myself included). The reason why I’m underscoring advanced is because writing types for a library is typically far (far) more difficult than writing types for an application. An example would be the types for React Redux (my goodness!).

The G2 Components library is pretty complex as it is. Adding TypeScript as a requirement makes working within the project even more difficult. This may limit ideation and contribution – critical for any project, especially one in it’s earlier stages.


There’s been a lot of performance improvements that have been made in G2’s core. From reducing Functional component wrappers, to reducing rendered DOM nodes, memoization, reworking Context * State bindings, and more.

This initially started when I attempted to prototype a potential Box Shadow design tool for Gutenberg.

GIF demonstrating the Box Shadow design tool prototyping.

After noticing some sluggishness (ugh), I reached out to Diego Haz (creator of Reakit and awesome human) for some help! He submitted an update, which both resolved the immediate problem and kickstarted my desires for making G2 Components fast by default. The hard part is to do it without affecting or degrading the desired component API experience (e.g. how custom CSS can be easily and seamlessly compiled).

I’ll expand more on performance in an upcoming blog post. For now, here’s are some quick before/after results.

Below is a screenshot of a mock Design Tool UI – maybe one that can be used for Box Shadow settings. The control enables a user to add a bunch of settings. In order words, a list (or collection) of items, each with their own values.

Screenshot of a mock design tool.

Previously, updating just one value from an individual item would cause the entire thing to re-render. This puts a tremendous amount of computational load, resulting in obvious jank and lag in the browser.

Check out the rendering flame chart of shame (haha):

A screenshot of (massive) render updates from React’s DevTools.

(Green indicates components that have re-rendered. Grey indicates components that have not re-rendered.)

After making the performance updates and strategizing how multi-item state updates should be handled (from a Design Tool perspective), we now have a much (much) nicer render chart:

A screenshot of improved render updates from React’s DevTools.

Notice how only a tiny bit of the chart is in green. That’s the tiny bit of UI we updated.

This performance strategy scales up to even 200+ items – a scenario that’s highly unlikely (we should probably limit adding 200+ box shadows, haha).

A screenshot from React DevTools visualizing (no) re-renders for 200 items.

In case you’re wondering, the re-render did happen. You just have to zoom in a bit to see it in the charts.

Zooming into React DevTools to locate the individual item re-render.

Without this state management strategy, I think updating a single value would most likely crash your browser.

If you’re curious about this prototype, you can check it out here.

In Conclusion

The last chunks of updates focused on things that you may not see from the library (e.g. new components). However, they are certainly things you can feel. From inline documentation to improving development experiences to seamless lower-level performance optimizations to scale up and unlock Design Tool potential. All of things updates contribute to the core principles of G2 Components that focus on improving UI experiences for all.

By Q

I specialize in Design Systems, Interaction, and UI.
I'm a Principal Designer at Automattic.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s