message: docs: add docs for custom should-forward-prop
diff: @@ -89,3 +89,60 @@ const Card = chakra("div", {
  },
  })
  ```
  +
  +### Allowing custom props to be forwarded
  +
  +By default, the `chakra` factory only filters chakra related style props from
  +getting to the DOM. For more fine-grained control of how and what prop should be
  +forwarded, pass the `shouldForwardProp` option.
  +
  +Here's a simple example that allows all props (including chakra's style props)
  +to pass through except the `sample` prop.
  +
  +```jsx live=false
  +const Div = chakra("div", {
  + shouldForwardProp: (prop) => !["sample"].includes(prop),
  +})
  +```
  +
  +Another example that combines the default `shouldForwardProp` from Chakra UI
  +with custom logic.
  +
  +```jsx live=false
  +import { shouldForwardProp } from "@chakra-ui/react"
  +
  +const Div = chakra("div", {
  + shouldForwardProp: (prop) => {
  + // don't forward Chakra's props
  + const isChakraProp = !shouldForwardProp(prop)
  + if (isChakraProp) return false
  +
  + // else, only forward `sample` prop
  + return ["sample"].includes(prop)
  + },
  +})
  +```
  +
  +To filter non-HTML attributes, you can leverage
  +[@emotion/is-prop-valid](https://github.com/emotion-js/emotion/tree/master/packages/is-prop-valid)
  +package.
  +
  +```jsx live=false
  +import isValidHMTLProp from "@emotion/is-prop-valid"
  +import { shouldForwardProp } from "@chakra-ui/react"
  +
  +const Div = chakra("div", {
  + shouldForwardProp: (prop) => {
  + // don't forward Chakra's props
  + const isChakraProp = !shouldForwardProp(prop)
  + if (isChakraProp) return false
  +
  + // forward valid HTML props
  + const isValidProp = isValidHMTLProp(prop)
  + if (isValidProp) return true
  +
  + // else, only forward `sample` prop
  + return ["sample"].includes(prop)
  + },
  +})
  +```
  