From 87ca016133be8f945671f8cef3263c57b99fb8a2 Mon Sep 17 00:00:00 2001 From: Taylor Jones Date: Tue, 6 Dec 2022 12:07:44 -0600 Subject: [PATCH] docs(style): add forward ref docs (#12775) Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com> --- docs/style.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/style.md b/docs/style.md index 0e0889dd3188..4c9e37910107 100644 --- a/docs/style.md +++ b/docs/style.md @@ -64,6 +64,7 @@ row before the line. - [React](#react) - [Guidelines](#guidelines) - [Writing a component](#writing-a-component) + - [When to use `React.ForwardRef`](#when-to-use-reactforwardref) - [Translating a component](#translating-a-component) - [Working with messages that depend on state](#working-with-messages-that-depend-on-state) - [Using `useCallback` and `useMemo`](#using-usecallback-and-usememo) @@ -72,6 +73,14 @@ row before the line. - [Style](#style-1) - [Naming event handlers](#naming-event-handlers) - [Naming experimental code](#naming-experimental-code) + - [Testing](#testing) + - [Strategy](#strategy) + - [Organization](#organization) + - [Recipes](#recipes) + - [`ComponentName-test.js`](#componentname-testjs) + - [`ComponentName-test.a11y.js`](#componentname-testa11yjs) + - [`ComponentName-test.server.js`](#componentname-testserverjs) + - [Notes on manual testing](#notes-on-manual-testing) - [Sass](#sass) - [Guidelines](#guidelines-1) - [Author component styles using mixins](#author-component-styles-using-mixins) @@ -82,6 +91,9 @@ row before the line. - [Annotate relevant Sass values with SassDoc](#annotate-relevant-sass-values-with-sassdoc) - [Style](#style-2) - [Comments](#comments) + - [Testing](#testing-1) + - [Recipes](#recipes-1) + - [Public API](#public-api) @@ -224,6 +236,25 @@ _Note: not every component will mirror the structure above. Some will need to incorporate `useEffect`, some will not. You can think of the outline above as slots that you can fill if you need this functionality in a component._ +##### When to use `React.ForwardRef` + +From the [react docs](https://reactjs.org/docs/forwarding-refs.html), + +> Ref forwarding is an opt-in feature that lets some components take a ref they +> receive, and pass it further down (in other words, “forward” it) to a child. + +For the most part, components should utilize `React.ForwardRef` so that +consumers can impact or control the managing of focus, selection, or animations. + +Cases where a component _may not_ need to forward a ref include components that +render static content or do not render elements that are focusable, interactive, +or animatable. + +Note that adding a forwarded ref to a component should be considered a breaking +change. When creating a new component, even if you do not anticipate an explicit +need to provide a forwarded ref, it's likely still worthwhile to include one to +avoid unecessary breaking changes in the future. + #### Translating a component Certain components will need to expose a way for the caller to pass in