Skip to content

Commit

Permalink
docs(style): add forward ref docs (#12775)
Browse files Browse the repository at this point in the history
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
  • Loading branch information
tay1orjones and kodiakhq[bot] authored Dec 6, 2022
1 parent 69ca3d6 commit 87ca016
Showing 1 changed file with 31 additions and 0 deletions.
31 changes: 31 additions & 0 deletions docs/style.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ row before the </tbody></table> 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)
Expand All @@ -72,6 +73,14 @@ row before the </tbody></table> 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)
Expand All @@ -82,6 +91,9 @@ row before the </tbody></table> 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)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
<!-- prettier-ignore-end -->
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 87ca016

Please sign in to comment.