Skip to content

Create Widget + Add to Viewport

At a glance

Lives in: Blueprint API / User Interface - Create Widget returns: a User Widget object reference, usually typed to the widget class you selected - Add to Viewport returns: nothing - Can be empty: Create Widget can return None; Add to Viewport needs a valid widget target - Official docs: Create Widget and Add to Viewport

The one-minute version

  • Create Widget makes a new widget object. It does not put anything on the screen by itself.
  • Add to Viewport puts that widget on the player's screen. It does not create a new widget; it uses the widget reference you give it.
  • Keep the return value from Create Widget in a variable. If you remove the widget and then create it again later, you made a fresh object with fresh default state.
  • Owning Player should usually be the local PlayerController that owns this user interface (UI). In a one-player test, leaving it empty often seems fine; in split-screen, focus, input, and player-specific UI, it matters.
  • ZOrder is the viewport layer. Higher numbers draw above lower numbers.
  • For a real heads-up display (HUD), create the widget from the PlayerController or HUD setup path, not from a pawn that may be destroyed and respawned.

What they actually do

Create Widget constructs an instance of a Widget Blueprint class at runtime. The class is the asset you pick on the Class pin, such as WBP_HealthBar or WBP_PauseMenu.

That object is just a live UUserWidget instance. It can hold variables, run its construct logic, bind to dispatchers, and expose functions you call later. It is not visible until you place it somewhere visible.

Add to Viewport takes a live user widget and registers it with the game viewport so it can be drawn on the screen:

pseudocode of the engine behavior - not engine source

function ShowPauseMenu(PlayerController, PauseMenuClass):
    Widget = CreateWidget(PauseMenuClass, OwningPlayer = PlayerController)
    if Widget is None:
        return None

    Widget.AddToViewport(ZOrder = 100)
    return Widget

The important split is:

Create Widget      -> make the object
Add to Viewport    -> display that object
Remove from Parent -> detach that object from where it is displayed

Removing a widget from the viewport does not mean "save this widget forever," and creating another one later does not know about the old one's variables. The reference you store is what lets you decide whether to reuse the old object or intentionally create a fresh one.

Owning Player is not decoration

The Owning Player pin is the player/controller context for this widget. For a single-player HUD, that usually means:

Get Player Controller (Player Index 0)
-> Create Widget (Class = WBP_HUD, Owning Player = Return Value)
-> Promote Return Value to variable HUDWidget
-> Add to Viewport

That looks like extra wiring in the first project, but it pays for itself as soon as the widget cares about focus, input, the owning pawn, or local split-screen. A widget that knows its owning player can ask questions like "which player's controller created me?" without guessing that player index 0 is always correct.

If a tutorial creates a HUD in the character's BeginPlay, it can work for a prototype. The cost shows up on death and respawn: the pawn is the object most likely to be destroyed and replaced. The UI normally belongs to the player experience, so the PlayerController or HUD setup path is the sturdier home.

When it fails (and what failure does)

The common failures are reference and timing problems, not exceptions.

  1. The widget class is missing or invalid. Create Widget needs a real Widget Blueprint class. If the class input cannot produce a UserWidget, the useful result is no widget.
  2. The world or player context is wrong. UI is local presentation. Creating a screen widget on a server-only path or from an object without the right world/player context will not show a menu to the local player you meant.
  3. You did not store the return value. The widget may appear, but later you have no specific object reference to update, remove, or reuse.
  4. You created it repeatedly. A key press, overlap, or Tick path can create a new menu every time it runs. The screen may look like one menu while several widget instances are alive.
  5. You called Add to Viewport on an empty reference. This is still an object-reference bug. Guard optional widget variables with Is Valid.
  6. You expected old state after re-creating. A new widget starts from its default values. Values stored only inside the old widget are gone from the user's point of view unless you copied them back in.

There is no hidden retry. If creation fails, Unreal does not wait for the class to exist. If display fails, it does not create a backup UI. Your graph continues from whatever execution pins you wired, so print or breakpoint the widget reference when diagnosing.

The pattern everyone actually uses

For a normal single-player HUD:

PlayerController BeginPlay
-> Create Widget (Class = WBP_HUD, Owning Player = Self)
-> Is Valid Return Value
-> Set HUDWidget variable
-> Add to Viewport (ZOrder = 0)

For a pause menu:

Input Pause
-> Branch IsValid(PauseMenuWidget)
   false:
       Create Widget (Class = WBP_PauseMenu, Owning Player = Self)
       Set PauseMenuWidget

-> Branch PauseMenuWidget Is In Viewport
   false:
       Add to Viewport (ZOrder = 100)
   true:
       Remove from Parent

For a health bar, create the widget once, store it, bind it to the character's health-change dispatcher, then do one initial refresh:

Create Widget WBP_HealthBar
-> Store HealthBarWidget
-> Bind to Character.OnHealthChanged
-> HealthBarWidget.UpdateHealth(CurrentHealth, MaxHealth)
-> Add to Viewport

The C++ twin, for the curious (our own example code):

void ATrainingPlayerController::BeginPlay()
{
    Super::BeginPlay();

    if (!HUDClass)
    {
        return;
    }

    HUDWidget = CreateWidget<UUserWidget>(this, HUDClass);
    if (IsValid(HUDWidget))
    {
        HUDWidget->AddToViewport(0);
    }
}

What these nodes do not do

  • Create Widget does not display the widget.
  • Add to Viewport does not create a widget.
  • Neither node pauses the game, changes input mode, shows the mouse cursor, or gives keyboard focus to a menu.
  • Neither node updates health, ammo, score, or inventory for you. You still need to push data into the widget.
  • A widget variable is not a save file. If the level changes, normal world UI is destroyed with the world unless you rebuild it from persistent state.
  • A screen widget is local UI. It is not a replicated actor and does not appear on other clients because you created it on one machine.

Lookalikes - which one do I want?

Node / tool Use when Watch out
Create Widget You need a new UserWidget instance from a Widget Blueprint class. It is not visible yet. Store the return value.
Add to Viewport You want a full-screen or screen-layer widget shown in the game viewport. It affects the screen, not input mode or pause state.
Add to Player Screen You want viewport UI scoped to a specific local player, especially split-screen. It still needs the right owning player context.
Add Child You are putting one widget inside a panel in another widget. It is not the root viewport; the parent widget controls layout.
Remove from Parent You want to detach a widget from its current parent or viewport. It does not create a new copy later; your reference decides reuse.
Set Visibility You want to hide/show an existing widget without rebuilding it. Hidden widgets can still be alive and holding state.
Set Input Mode / Show Mouse Cursor You want the player to interact with menus. These are separate from displaying the widget.

Rule of thumb: create once when practical, store the reference, add/remove or show/hide that same object, and put player-owned UI setup on the PlayerController or HUD path.

Going deeper