Pmndrs.docs

Components and Properties

A list of all components and their properties.

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

View all flexbox properties
PropertyType
marginnumber, Percentage, "auto"
marginXnumber, Percentage, "auto"
marginYnumber, Percentage, "auto"
marginTopnumber, Percentage, "auto"
marginLeftnumber, Percentage, "auto"
marginRightnumber, Percentage, "auto"
marginBottomnumber, Percentage, "auto"
transformTranslateXnumber
transformTranslateYnumber
transformTranslateZnumber
transformScaleXnumber
transformScaleYnumber
transformScaleZnumber
transformRotateXnumber
transformRotateYnumber
transformRotateZnumber
positionType"absolute", "relative", "count"
insetnumber, Percentage
positionTopnumber, Percentage
positionLeftnumber, Percentage
positionRightnumber, Percentage
positionBottomnumber, Percentage
alignContent"count", "space-around", "space-between", "baseline", "stretch", "flex-end", "center", "flex-start", "auto"
alignItems"count", "space-around", "space-between", "baseline", "stretch", "flex-end", "center", "flex-start", "auto"
alignSelf"count", "space-around", "space-between", "baseline", "stretch", "flex-end", "center", "flex-start", "auto"
flexDirection"count", "row-reverse", "row", "column-reverse", "column"
flexWrap"count", "wrap-reverse", "wrap", "no-wrap"
justifyContent"count", "space-around", "space-between", "flex-end", "center", "flex-start", "space-evenly"
flexBasisnumber, Percentage
flexGrownumber
flexShrinknumber
widthnumber, Percentage, "auto"
heightnumber, Percentage, "auto"
minWidthnumber, Percentage
minHeightnumber, Percentage
maxWidthnumber, Percentage
maxHeightnumber, Percentage
aspectRationumber
bordernumber
borderXnumber
borderYnumber
borderTopnumber
borderLeftnumber
borderRightnumber
borderBottomnumber
overflow"visible", "scroll", "hidden"
paddingnumber, Percentage
paddingXnumber, Percentage
paddingYnumber, Percentage
paddingTopnumber, Percentage
paddingLeftnumber, Percentage
paddingRightnumber, Percentage
paddingBottomnumber, Percentage
gapnumber
gapRownumber
gapColumnnumber

Container

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.

View all properties for styling the background panel
PropertyType
zIndexOffsetnumber
receiveShadowboolean
castShadowboolean
backgroundColorColorRepresentation
backgroundOpacitynumber
panelMaterialClassMaterial class
borderOpacitynumber
borderColorColorRepresentation
borderRadiusnumber
borderLeftRadiusnumber
borderRightRadiusnumber
borderTopRadiusnumber
borderBottomRadiusnumber
borderTopLeftRadiusnumber
borderTopRightRadiusnumber
borderBottomRightRadiusnumber
borderBottomLeftRadiusnumber
borderBendnumber
scrollbarPanelMaterialClassMaterial class
scrollbarBackgroundOpacitynumber
scrollbarBackgroundColorColorRepresentation
scrollbarWidthnumber
scrollbarBorderRadiusnumber
scrollbarBorderLeftRadiusnumber
scrollbarBorderRightRadiusnumber
scrollbarBorderTopRadiusnumber
scrollbarBorderBottomRadiusnumber
scrollbarBorderTopLeftRadiusnumber
scrollbarBorderTopRightRadiusnumber
scrollbarBorderBottomRightRadiusnumber
scrollbarBorderBottomLeftRadiusnumber

Root

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. The Root component also allows to control the renderOrder and depthTest of the whole user interface.

<Root sizeX={2} sizeY={1} flexDirection="row">
  <Container flexGrow={1} backgroundColor="red" />
  <Container flexGrow={1} backgroundColor="green" />
</Root>
View all properties specific to the Root component
PropertyType
anchorX"left", "center", "right"
anchorY"top", "center", "bottom"
sizeXnumber
sizeYnumber
renderOrdernumber
depthTestboolean

Fullscreen

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>
View all properties specific to the Fullscreen component
PropertyType
attachCameraboolean
distanceToCameranumber
renderOrdernumber
depthTestboolean

Image

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="https://github.com/pmndrs/uikit/raw/main/docs/getting-started/example.jpg" width={100} />
</Root>
View all properties specific to the Image component
PropertyType
srcstring, Texture
objectFit"fill", "cover"
keepAspectRatioboolean

SuspendingImage

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>

Portal

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>

Video

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>
View all properties specific to the Video component
PropertyType
srcstring, MediaStream
volumenumber
preservesPitchboolean
playbackRatenumber
mutedboolean
loopboolean
autoplayboolean

Text

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>
View all properties specific to the Text component
PropertyType
colorColorRepresentation
opacitynumber
textAlign"left", "center", "right"
verticalAlign"top", "center", "bottom"
letterSpacingnumber
lineHeightnumber
fontSizenumber
wordBreak"keep-all", "break-all", "break-word"
fontFamilystring
fontWeightnumber, "bold", "thin", "extra-light", "light", "normal", "medium", "semi-bold", "extra-bold", "black", "extra-black"

Input

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>
View all properties specific to the Input component
PropertyType
multilineboolean
valuestring
defaultValuestring
onValueChange(value: string) => void
tabIndexnumber
disabledboolean
type"text", "password"
caretColorColorRepresentation
caretOpacityopacity
caretWidthnumber
caretBorderOpacitynumber
caretBorderColorColorRepresentation
caretBorderRadiusnumber
caretBorderLeftRadiusnumber
caretBorderRightRadiusnumber
caretBorderTopRadiusnumber
caretBorderBottomRadiusnumber
caretBorderTopLeftRadiusnumber
caretBorderTopRightRadiusnumber
caretBorderBottomRightRadiusnumber
caretBorderBottomLeftRadiusnumber
caretBorderBendnumber
caretBordernumber
caretBorderXnumber
caretBorderYnumber
caretBorderTopnumber
caretBorderLeftnumber
caretBorderRightnumber
caretBorderBottomnumber
selectionColorColorRepresentation
selectionOpacityopacity
selectionBorderOpacitynumber
selectionBorderColorColorRepresentation
selectionBorderRadiusnumber
selectionBorderLeftRadiusnumber
selectionBorderRightRadiusnumber
selectionBorderTopRadiusnumber
selectionBorderBottomRadiusnumber
selectionBorderTopLeftRadiusnumber
selectionBorderTopRightRadiusnumber
selectionBorderBottomRightRadiusnumber
selectionBorderBottomLeftRadiusnumber
selectionBorderBendnumber
selectionBordernumber
selectionBorderXnumber
selectionBorderYnumber
selectionBorderTopnumber
selectionBorderLeftnumber
selectionBorderRightnumber
selectionBorderBottomnumber

Svg

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>
View all properties specific to the SVG component
PropertyType
srcstring
colorColorRepresentation
opacitynumber
panelMaterialClassMaterialClass

Icon

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>
View all properties specific to the SVGIconFromText component
PropertyType
textstring
svgHeightnumber
svgWidthnumber
colorColorRepresentation
opacitynumber
panelMaterialClassMaterialClass

Content

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>
View all properties specific to the Content component
PropertyType
depthAlign"back", "center", "front"
keepAspectRatioboolean

CustomContainer

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>

DefaultProperties

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>

FontFamilyProvider

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>

Conditional Properties

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:

NameExplanation
focuswhen the user has focussed the element (currently only available on input)
hoverwhen the user hovers over the element
activewhen the users clicks (pointer down) on the element
smwhen the width of the root element is bigger than 640
mdwhen the width of the root element is bigger than 768
lgwhen the width of the root element is bigger than 1024
xlwhen the width of the root element is bigger than 1280
2xlwhen the width of the root element is bigger than 1536
darkwhen the preferred color scheme is dark
<Fullscreen flexDirection="column" md={{ flexDirection: 'row' }}>
  <Container flexGrow={1} backgroundColor="red" />
  <Container flexGrow={1} backgroundColor="green" />
</Fullscreen>

Preferred Color Schemes

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

Event Properties

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

View all event handlers
PropertyType
onWheel(event: ThreeEvent<WheelEvent>) => void
onPointerUp(event: ThreeEvent<PointerEvent>) => void
onPointerOver(event: ThreeEvent<PointerEvent>) => void
onPointerOut(event: ThreeEvent<PointerEvent>) => void
onPointerMove(event: ThreeEvent<PointerEvent>) => void
onPointerLeave(event: ThreeEvent<PointerEvent>) => void
onPointerEnter(event: ThreeEvent<PointerEvent>) => void
onPointerDown(event: ThreeEvent<PointerEvent>) => void
onPointerCancel(event: ThreeEvent<PointerEvent>) => void
onDoubleClick(event: ThreeEvent<MouseEvent>) => void
onContextMenu(event: ThreeEvent<MouseEvent>) => void
onClick(event: ThreeEvent<MouseEvent>) => void
onSizeChange(width: number, height: number) => void
onIsClippedChange(isClipped: boolean) => void
onScroll(scrollX: number, scrollY: number, scrollPosition: Signal<Vector2Tuple>, event?: ThreeEvent<WheelEvent | PointerEvent>) => boolean | void

Ref

Each component exposes the ComponentInternals when using a ref. The component internals provide you with access to

PropertyExplanation
borderInseta tuple containing the border sizes on all 4 sides [top, right, bottom, left]
paddingInseta tuple containing the padding sizes on all 4 sides [top, right, bottom, left]
centerthe offset between from the element's center to its parent's center
sizethe outer width/height of the element
interactionPanelthe mesh added to the scene graph to capture events
scrollPositionthe x/y scroll position of the children when the element is scrollable
pixelSizethe size of one pixel
maxScrollPositionthe maximum x/y scroll position, based on the size of the children
isClippedexploses whether the element is fully clipped by some ancestor
setStyleset the styles of the element (the provided styles have a higher precedence then the element's properties)
getStyleget the object last written to setStyle
getComputedPropertyread the current value for any property (combines default properties, direct properties, and styles)