---
title: "QuartzUIWidgetComponent: declaration reference"
description: "Quartz UI 0.57.0-dev: QuartzUIWidgetComponent: declaration reference. Source-reviewed guidance, usage and limitations."
status: approved
visibility: public
sourceRevision: fe5b709ec900e282b50e58b819a25041945005f9
reviewedAt: 2026-09-24
---

# QuartzUIWidgetComponent: declaration reference

> **0.57.0-dev · beta source documentation.** Native, Blueprint, Editor and rendering examples are source-reviewed, not executed in Unreal during this scan. See [validation and limits](https://betterbuilt.games/docs/quartz-ui/evidence).

Pinned source (source: `Source/QuartzUIRuntime/Public/QuartzUIWidgetComponent.h`) · [integration recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiwidgetcomponent) · [practical guide](https://betterbuilt.games/docs/quartz-ui/rendering)

## UQuartzUIWidgetComponent

**Public type.** Passive QuartzUI presentation for world-space geometry or Unreal's projected screen-space widget layer. World space uses the normal UWidgetComponent render-target path, so the component has a real world-unit size, perspective, and scene occlusion. Screen space keeps a pixel-sized presentation anchored to this component. This component intentionally never accepts hardware input.

**Prerequisites / integration:** Exact-player app/view and real supported RHI for rendering; project-owned HTML/materials. Use the [QuartzUIWidgetComponent recipe](https://betterbuilt.games/docs/quartz-ui/inventory#quartzuiwidgetcomponent) in the host module `QuartzUIRuntime`.

**Minimal example / lifecycle:** Add QuartzUI Spatial Widget; InitializeApp(App, Player). Owns view only when initialized as owner; releases on teardown.

**Avoid:** Expecting pointer/IME support or ignoring second render-target cost. Match the exact declaration below; dependent DTOs/enums are values used by this owner, not independent systems.

Exact source line (source: `Source/QuartzUIRuntime/Public/QuartzUIWidgetComponent.h#L27`)

## Complete header

Source snapshot, not an additional example. Unreal annotations distinguish exposed Blueprint nodes from native-only/private methods.

```cpp
#pragma once

#include "Components/WidgetComponent.h"
#include "QuartzUIApp.h"

#include "QuartzUIWidgetComponent.generated.h"

class ULocalPlayer;
class UQuartzUIAppAsset;
class UQuartzUIView;
class UQuartzUIWidget;

/**
 * Passive QuartzUI presentation for world-space geometry or Unreal's projected
 * screen-space widget layer.
 *
 * World space uses the normal UWidgetComponent render-target path, so the
 * component has a real world-unit size, perspective, and scene occlusion.
 * Screen space keeps a pixel-sized presentation anchored to this component.
 * This component intentionally never accepts hardware input.
 */
UCLASS(
	BlueprintType,
	ClassGroup = "QuartzUI",
	hidecategories = (Interaction),
	meta = (BlueprintSpawnableComponent, DisplayName = "QuartzUI Spatial Widget"))
class QUARTZUIRUNTIME_API UQuartzUIWidgetComponent : public UWidgetComponent
{
	GENERATED_BODY()

public:
	UQuartzUIWidgetComponent(const FObjectInitializer& ObjectInitializer);

	/**
	 * Creates an independently owned logical view from an app asset and presents
	 * it on this component. The view is closed when this component ends play.
	 */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Spatial")
	bool InitializeApp(const UQuartzUIAppAsset* App, ULocalPlayer* OwningLocalPlayer);

	/**
	 * Presents an existing logical view. The caller retains ownership of the
	 * view; this component only owns its presentation.
	 */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Spatial")
	bool AttachToView(UQuartzUIView* View);

	/**
	 * Creates a standalone browser presentation without a UQuartzUISubsystem view.
	 * This is the lightest setup when typed project contracts are not required.
	 */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Spatial")
	bool InitializeStandalone(const FQuartzUIAppDefinition& Definition);

	/** Releases this browser presentation and closes only a view created by InitializeApp. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Spatial")
	void ReleaseQuartzUI();

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Spatial")
	UQuartzUIWidget* GetQuartzUIWidget() const { return QuartzUIWidget; }

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Spatial")
	UQuartzUIView* GetAttachedView() const;

	UFUNCTION(BlueprintPure, Category = "QuartzUI|Spatial")
	bool IsQuartzUIInitialized() const { return QuartzUIWidget != nullptr; }

	/** Explicit visibility/budget control for pooled or distant spatial views. */
	UFUNCTION(BlueprintCallable, Category = "QuartzUI|Spatial")
	bool SetQuartzUIRuntimeSuspended(bool bSuspended);

	virtual void OnRegister() override;
	virtual void EndPlay(const EEndPlayReason::Type EndPlayReason) override;

private:
	void ApplyPassivePresentationPolicy();
	bool InstallPresentation(UQuartzUIWidget* Candidate, UQuartzUIView* View, bool bCandidateOwnsView);
	void ReleasePresentation(bool bCloseOwnedView);

	UPROPERTY(Transient)
	TObjectPtr<UQuartzUIWidget> QuartzUIWidget;

	UPROPERTY(Transient)
	TWeakObjectPtr<UQuartzUIView> OwnedView;
};
```

Canonical HTML: https://betterbuilt.games/docs/quartz-ui/reference-quartzuiwidgetcomponent