@react-three/flex


Placing content in THREE.js is hard. @react-three/flex brings the webs flexbox spec to react-three-fiber.
It is based on Yoga, Facebook's open source layout engine for react-native.

``bash
npm install @react-three/flex
`

Simply create layouts by wrapping your 3D objects in different instances inside a container. This way they will be automatically placed in the 3D space following the flexbox specification just like in the DOM.

`jsx
import { Flex, Box } from '@react-three/flex'

const Layout = () => (








)
`

You can tweak the container and the boxes using standard CSS flex properties, like flexDirection or justifyContent for the container and flexGrow for the boxes. There are also _shorthands_, like align and justify. See the props docs below for more info.

$3

When positioning items, react-three-flex needs to know where the object anchor is: Yoga Layout expects the object position to be relative to the upper left corner, which is the same as the DOM expects.

Most THREE.js geometries, though, are positioned relative to the object center. To tell react-three-flex that your positioning is relative to the center you need to set the centerAnchor prop to true.

`jsx



`

If you nest elements, though, you need to set it to false. See Nesting.

!Anchors

$3

By default @react-three/flex controls elements position only. In some cases you may want to control element sizing too. Since @react-three/flex has no information about how the inner content size works, you need to set your content size manually. To do so @react-three/flex provides you the container size in two ways:

- Using a children render function:

`jsx


{(width, height) => }


`

- Using a hook:

`jsx
function Inner() {
const [width, height] = useFlexSize()
return
}

function Outer() {
return (



`

Remember that the useFlexSize hook works ONLY if your is outside the component.

$3

While the DOM's Flexbox has full control over all the changes of the tree, @react-three/flex runs on React, hence it has no way to know if a children size or shape has changed. For performance reasons Flex layout calculation _does not run every frame_, and it has to be triggered manually in some cases.

What will trigger a reflow:

- props changes (alignItems, size, ...)
- props changes (flexGrow, margin, ...)
- and rerenders with children differences

`jsx
function AnimatedBox() {
// Since is inside the component, setting the state will rerender it, thus causing a reflow.
// ⚠️ If were outside this component, this would NOT cause a reflow!
const [state, setState] = useState(true)
useInterval(() => setState((s) => !s), 1000)
return (



`

This will NOT cause a reflow!

`jsx
function AnimatedBox() {
// ⚠️ Setting state does not rerender since it's in the parent
// ‼️ No Reflow!!
const [state, setState] = useState(true)
useInterval(() => setState((s) => !s), 1000)
return (



)
}

function Layout() {
return (



`

For every other case (setting size with the useFrame hook, performing react-spring animation, or are not rerendered) you'll need to manually cause a reflow, using the useReflow() hook. Reflows requests are batched every frame so you can call it from hundreds of components without performance issues.

Animation with useFrame():

`jsx
function AnimatedBox() {
const ref = useRef()
const reflow = useReflow()
useFrame(({ clock }) => {
ref.current.scale.x = 1 + Math.sin(clock.getElapsed())
reflow()
})
return (


`

outside of component:

`jsx
function AnimatedBox() {
const [state, setState] = useState(true)
useInterval(() => setState((s) => !s), 1000)
const reflow = useReflow()
useEffect(reflow, [state])
return (

`

$3

@react-three/flex differs from DOM Flexbox in that it relies on a parent container for the root flex. It is required to specify its dimensions using size prop for wrapping and to be responsive.

`jsx

{/ ... /}

`

⚠️ WATCH OUT! Yoga flexbox engine uses whole integer numbers to perform layout calculation to preserve precision - @react-three/flex multiplies every element size and flex prop by the scaleFactor of the root flex container. By default it's 100, and works well for small scenes. If you use a different scene scale, make sure to tweak it accordingly.

!Bounds

$3

Another important difference with DOM Flexbox is that you have to specify the plane of the container in 3D. The elements will be positioned in the 2D plane given by the two axes, using width and height calculated along the two axes.

The 2D flex container width and height will be calculated by looking at the size prop with respect of the chosen axes (100 for x and 200 for y in this example).

The default plane is xy, the other possibilites are yz and xz.

`jsx

{/ ... /}

`

!Axes Orientation

$3

For every and component you can specify the margin and padding like in DOM elements.

`jsx





`

!Margin

$3

Since a component works the same way as a DOM one, you can easily make complex layouts by nesting flex containers.

`jsx













`

$3

When building responsive layouts you might need to synchronize the size of the 3D Flex container with the DOM, for example to synchronize scroll position or to modify the height of a scroll container.
To make it easier, you can use the onReflow prop on the root component that will be called every time the flex layout is recalculated - e.g. when any content changes.

`jsx
...}>
{/ ... /}

`

API

You can find a full list of props here.

`jsx
size={[1, 1, 1]} // Total size of the flex container, see above
position={[0, 0, 0]} // Default - position for the flex container in the scene
direction="ltr" // Default - right to left or right to left
plane="xy" // Default - plane axes, see above
scaleFactor={100} // Default - integer scale factor, see above (Sizing)
onReflow={fn} // Called everytime the layout is recalculated
{...R3FlexProps} // Standard Flexbox props, described below
>
{/ ... /}

`

`jsx
centerAnchor // If the inner content position is relative to its center, see above (Anchors)
{...R3FlexProps} // Standard Flexbox props, described below
>


`

Or you can pass a function as children:

`jsx
{(width, height) => }
`

$3

Both and components share the same Flexbox props API from Yoga. The library also provides string and number inputs for convenience and shorthands.

Example:

`jsx
// Flex with padding top set to 10, alignItems to 'center', justifyContent to 'space-around' and flexWrap to 'wrap'

{/ ... /}

``