Components and Properties

Just like in html/css, all uikit components have a certain properties in common, such as properties to define the position and size inside the layout, as well as, properties that are inherited, such as color. An overview of all available base properties can be found below.

lineHeight Note:

Just like in html/css, numeric line heights represent multipliers (e.g. 1.3) while line heights with a px suffix represent absolute pixel values e.g. 20px.

zIndexOffset Explanation:
Generally using zIndex is recommended as it behaves just like zIndex in the browser. zIndexOffset allows to manipulate the internal default order deduced from the UI hierachy, giving the developer the option to shift the order of specific elements backwards or forwards making them appear behind or infront of other elements. Note that sibling elements are treated as having the same UI hiearchy and are therefore not explicitly ordered. Using zIndexOffset={1} can be faster then using zIndex as it allows to order sibling elements of the same type e.g. with two overlapping panels beeing siblings in the UI hiearchy.

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>

The Container has exactly all the base properties and nothing more.

The Fullscreen component wraps the Container 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 Container 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.

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

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.

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

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.

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

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 exactly the base properties, since properties such as fontWeight are inherited and therefor available on all components.

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

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 input is disabled, the current value, the defaultValue, an onValueChange listener, and the tabIndex to customize the tab order.

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

The Textarea component extends the Input component but supports multi-line inputs.

<Textarea fontWeight="bold" defaultValue="Hello World" />

The Svg component allows rendering an Svg file. The URL of the file is provided in the src property. Alternatively, the content of the svg file cant directly be provided to the component instead of the url using the content property.

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

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}.

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

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.

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

In some cases you might want to overwrite the defaults for all descendants inside a component or need to overwrite set a property with a higher precendence then a property from a hover conditional.

Using the '*' property, you can set properties that overwrite the default for all descendants.

<Fullscreen flexDirection="column" gap={8} {...{ '*': { backgroundColor: 'red' } }}>
  <Container width={64} height={64} />
  <Container width={64} height={64} />
</Fullscreen>

In certain cases you want to make sure a property is applied even if there is a hover conditional writing the same property. In this case, you can use important.

<Container hover={{ backgroundColor: 'green' }} important={{ backgroundColor: 'red' }} />

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.

Using a ref, react developers can get access to the uikit component to imperatively change properties or access internal values. A full overview over all methods and properties exposed on all uikit component can be found here.