From af3b37ece319f86cf083a1d5b518512aba11c3ff Mon Sep 17 00:00:00 2001 From: Andy Edwards Date: Mon, 11 Jun 2018 21:41:20 -0500 Subject: [PATCH] docs(forwarding-refs.md): add warning to third-party library maintainers (#968) * docs(forwarding-refs.md): add warning to third-party library maintainers * Update forwarding-refs.md * Update forwarding-refs.md * Update forwarding-refs.md * tweaks --- content/docs/forwarding-refs.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/content/docs/forwarding-refs.md b/content/docs/forwarding-refs.md index 9b9dfbe2..2eef62a2 100644 --- a/content/docs/forwarding-refs.md +++ b/content/docs/forwarding-refs.md @@ -37,6 +37,12 @@ Here is a step-by-step explanation of what happens in the above example: > >Ref forwarding is not limited to DOM components. You can forward refs to class component instances, too. +## Note for component library maintainers + +**When you start using `forwardRef` in a component library, you should treat it as a breaking change and release a new major version of your library.** This is because your library likely has an observably different behavior (such as what refs get assigned to, and what types are exported), and this can break apps and other libraries that depend on the old behavior. + +Conditionally applying `React.forwardRef` when it exists is also not recommended for the same reasons: it changes how your library behaves and can break your users' apps when they upgrade React itself. + ## Forwarding refs in higher-order components This technique can also be particularly useful with [higher-order components](/docs/higher-order-components.html) (also known as HOCs). Let's start with an example HOC that logs component props to the console: