Components and Properties

All components in uikit use flexbox properties to define the position and size inside the layout. An overview of all available flexbox properties can be found below and here.

The Container componet is a basic UI component that allows wrapping children and rendering a Panel into the background. It corresponds to the HTML div element.

<Container backgroundColor="red">
  <Text>...</Text>
  <Image src="..." />
</Container>

In addition to the flexbox properties, the container has properties for styling its background panel and the scrollbars.

Every layout needs to start with a Root component. The Root component has all the properties of a Container component. The pixelSize property of the Root component allows you to specify the relation of pixels inside the layout with the three.js units in the scene. The anchorX and anchorY properties allow you to specify where the Root component is anchored in relation to its position. The sizeX and sizeY properties can be used to give the layout a fixed size in three.js units.

<Root sizeX={2} sizeY={1} flexDirection="row">
  <Container flexGrow={1} backgroundColor="red" />
  <Container flexGrow={1} backgroundColor="green" />
</Root>

The Fullscreen component wraps the Root component and binds its content directly to the viewport based on the provided distanceToCamera. The Fullscreen component automatically sets the correct pixelSize, sizeX, and sizeY properties on the Root component so that pixel sizes align with the pixels of the screen. In addition, the Fullscreen component has all the properties of the Container component.

<Fullscreen flexDirection="row">
  <Container flexGrow={1} backgroundColor="red" />
  <Container flexGrow={1} backgroundColor="green" />
</Fullscreen>

The Image component has the same properties and functionalities as a Container component but allows you to render an image inside it. The Image component corresponds to the HTML img element. The Image component has the src property, which can take an URL or a three.js texture. The Image component automatically sets the aspectRatio property based on the src property. This behavior can be turned off through keepAspectRatio={false}. The objectFit property can also be used to cover or fill the image in case the aspect ratio cannot be preserved by the layout engine or was overwritten by the user.

<Root>
  <Image src="example.jpg" width={100} />
</Root>

The default image doesn't use react's suspense but rather loads the image silently. To explicitly control how the image behaves when loaded, use the SuspendingImage component. The component can be used to display a fallback component while the image is loading. It has the same properties as the Image component.

<Suspense fallback={
    <Container width={200} aspectRatio={1} alignItems="center" justifyContent="center">
      <LoadingSpinner/>
    </Container>
  }
>
  <SuspendingImage src="..." width={200}>
</Suspense>

The Portal component uses the Image component under the hood to render its children into a render target, which is displayed on the surface of the Portal component. In contrast to the Image component, the Portal component doesn't have a default aspectRatio or an src property. The size of the portal is completly controlled through the flexbox properties, the resolution of the portal is equal to the size multiplied by the dpr property, which defaults to the system dpr.

<Root>
  <Portal width={200} aspectRatio={1}>
    <mesh>
      <boxGeometry />
      <meshBasicMaterial color="red" />
    </mesh>
  </Portal>
</Root>

The Video component has the same properties and functionalities as a Image component but allows you to render an video inside it. The Video component corresponds to the HTML video element. The Video component has the src, volume, preservesPitch, playbackRate, muted, loop, and autoplay property to setip the video and can even be used to play media streams.

To control playing the video the Video provide the html video element through a provide, that can be consumed by its children through useVideoElement to create video controls. Additionally, the html video element can be received from the parent of the Video using ref.current.element.

<Root>
  <Video src="example.mp4" autoplay width={100} />
</Root>

The Text component allows you to render of text and is highly intertwined with the layout engine to allow the layout engine to measure and influence the text layout (e.g., how the text should be broken up). The Text component has several properties aligned with the CSS text properties such as letterSpacing, lineHeight, fontSize, wordBreak, fontFamily, and fontWeight. In addition, the Text component has all the properties available in the Container component.

<Root>
  <Text fontWeight="bold">Hello World!</Text>
</Root>

The Input component extends the Text component and allows the user to change the text through their preferred input device. The Input component has all the formatting capabilities as the Text element. Additionally, it allows specifying whether the multiline texts are allowed (similar to a textarea), whether the input is disabled, the current value, the defaultValue, an onValueChange listener, and the tabIndex to customize the tab order.

<Root>
  <Input fontWeight="bold" defaultValue="Hello World" />
</Root>

The Svg component allows rendering an Svg file. The URL of the file is provided in the src property. Additionally, the opacity, color, and panelMaterialClass properties can be used to transform the appearance of the Svg, and all the Container properties are available for styling the background panel.

<Root>
  <Svg src="..." width={100} />
</Root>

The Icon component only differs from the SVG component in how the SVG content is provided. The Icon component takes a text property, which must contain the source code of the SVG. This component helps to inline small SVG files in use cases such as icons. For example, this component is used to implement the uikit-lucide icon pack. When creating the component, the svgWidth and svgHeight properties must be provided since three.js currently doesn't respect the viewport defined in svg files.

<Root>
  <Icon text="..." svgWidth={16} svgHeight={16} width={20} />
</Root>

The Content component allows you to include any R3F/Three.js element into the layout. Since the children inside the Content component can be 3-dimensional objects, their alignment on the z-axis can be controlled with the depthAlign property. By default the content will preserve the aspect ratio of the 3D objects. In case the 3D objects should be sized independent from its aspect ratio, set keepAspectRatio={false}.

<Root>
  <Content width={100}>
    <Gltf src="...">
  </Content>
</Root>

The CustomContainer component integrates a 2D panel with a custom material into the UI. The component is not instanced but provides complete control over the material of the panel.

<Root>
  <CustomContainer width={200} height={200}>
    <shaderMaterial fragmentShader="" vertexShader="" />
  </CustomContainer>
</Root>

The DefaultProperties component allows you to override the default properties for all children. HTML/CSS uses the concept of inheritance to change properties on all children. In uikit the DefaultProperties component can be used to achieve the same goal. In HTML/CSS, property inheritance is implicit; the DefaultProperties component allows explicit expression of what properties are inherited by its children.

<Root>
  <DefaultProperties color="red" fontWeight="bold">
    <Text>1</Text>
    <Container>
      <Text>2</Text>
    </Container>
    <Text>3</Text>
  </DefaultProperties>
</Root>

The FontFamilyProvider component allows you to use the specified font families in all its children. The fonts must be compiled into an MSDF texture and a JSON containing glyph information, because uikit uses MSDF font rendering. More information on how to do this can be found here.

<FontFamilyProvider
  roboto={{
    light: 'url-to-json',
    medium: 'url-to-json',
    bold: 'url-to-json',
  }}
  otherFont={{...}}
>
  {...children}
</FontFamilyProvider>

uikit allows you to declare properties that depend on the element's interaction state, similar to CSS selectors, such as :hover. Conditional properties also enable elements in the layout to be responsive based on several breakpoints. uikit supports a range of conditional properties:

<Fullscreen flexDirection="column" md={{ flexDirection: 'row' }}>
  <Container flexGrow={1} backgroundColor="red" />
  <Container flexGrow={1} backgroundColor="green" />
</Fullscreen>

By default, uikit inherits the preferred color scheme from the browser. Developers and designers can use the preferred color scheme to support users' preference for dark and light modes. The preferred color scheme can be controlled using setPreferredColorScheme and getPreferredColorScheme. The function basedOnPreferredColorScheme lets you create themes containing colors that change depending on the preferred color scheme.

setPreferredColorScheme("light")

const theme = basedOnPreferredColorScheme({
  light: {
    primary: "red"
  },
  dark: {
    primary: "green"
  }
})

<Container backgroundColor={theme.primary} width={100} height={100} />

All Components support all R3F event handlers. Additionally, event handlers for onSizeChange, onIsClippedChange, and onScroll can be added to all components.

Each component exposes internal information when using a ref. For instance, the container component exposes internals of the type ContainerRef. The component internals provide you with access to