[UxmlElement]
public class StackView : BaseVisualElement, IEventHandler, IResolvedStyle, ITransform, ITransitionAnimations, IExperimentalFeatures, IVisualElementScheduler, IContextOverrideElement, IAdditionalDataHolder

Remarks

The StackView component provides a sophisticated navigation container that manages a stack of visual elements with smooth animated transitions. It follows a last-in-first-out (LIFO) pattern, where only the topmost item is visible and active at any time.

The items are added to the stack using the Push method. The top item is the current item. The current item can be removed using the Pop method. The item below the current item becomes the new current item. The current item can be replaced using the Replace method. The item below the current item is removed and the new item is added.

Key features:

Stack-based navigation with push, pop, and replace operations
Customizable animation descriptions for each transition type
Lifecycle events for items (activating, activated, deactivating, deactivated, removed)
Support for both StackViewItem and regular VisualElement children
Depth tracking and empty state detection
Non-blocking animations with busy state checking

StackView is ideal for implementing wizard-style interfaces, slideshow presentations, or any UI flow that requires sequential navigation with the ability to go back to previous states.

NOTE: Each item in the stack can be either a StackViewItem or any VisualElement, which will be automatically wrapped in a StackViewItem.

Examples

Basic stack view with navigation. Creating a simple two-page navigation with stack view.

var stackView = new StackView();
// Push first item
var page1 = new Box();
page1.Add(new Text );
var nextButton = new Button ;
page1.Add(nextButton);
stackView.Push(page1);
// Push second item when button clicked
nextButton.clicked += () =>
{
var page2 = new Box();
page2.Add(new Text );
var backButton = new Button ;
page2.Add(backButton);
stackView.Push(page2);

// Pop back to first item
backButton.clicked += () => stackView.Pop();

};

Wizard interface with replace functionality. Implementing a wizard with skip functionality.

var stackView = new StackView();
// Initial welcome screen
var welcomePage = CreateWelcomePage();
stackView.initialItem = welcomePage;
void CreateStep(int stepNumber)
{
var stepPage = new Box();
stepPage.Add(new Text { text = $"Step " });
var nextButton = new Button { text = "Next" };
var skipButton = new Button { text = "Skip to End" };

stepPage.Add(nextButton);
stepPage.Add(skipButton);

nextButton.clicked += () => CreateStep(stepNumber + 1);
skipButton.clicked += () =>
{
    // Replace all items with final page
    stackView.Replace(null, CreateFinalPage());
};

stackView.Push(stepPage);

}

Using lifecycle events. Handling item lifecycle events.

var item = new StackViewItem(new Text { text = "Content" });
item.activating += () =>
{
Debug.Log("Item is about to become active");
// Prepare item, load data, etc.
};
item.activated += () =>
{
Debug.Log("Item is now active");
// Start animations, play sounds, etc.
};
item.deactivating += () =>
{
Debug.Log("Item is about to be deactivated");
// Save state, pause operations, etc.
};
item.deactivated += () =>
{
Debug.Log("Item is now inactive");
};
item.removed += () =>
{
Debug.Log("Item has been removed from stack");
// Clean up resources
};
stackView.Push(item);

Custom slide animations. Creating iOS-style slide navigation animations.

var stackView = new StackView();
// Configure slide-left animation for push
stackView.pushEnterAnimation = new AnimationDescription
{
durationMs = 300,
easing = Easing.OutQuad,
callback = (element, t) =>
{
var offset = 100 * (1 - t);
element.style.translate = new Translate(new Length(offset, LengthUnit.Percent), 0);
element.style.opacity = t;
}
};
stackView.pushExitAnimation = new AnimationDescription
{
durationMs = 300,
easing = Easing.InQuad,
callback = (element, t) =>
{
var offset = -50 * t;
element.style.translate = new Translate(new Length(offset, LengthUnit.Percent), 0);
element.style.opacity = 1 - t * 0.5f;
}
};
// Configure slide-right animation for pop
stackView.popExitAnimation = new AnimationDescription
{
durationMs = 300,
easing = Easing.InQuad,
callback = (element, t) =>
{
var offset = 100 * t;
element.style.translate = new Translate(new Length(offset, LengthUnit.Percent), 0);
element.style.opacity = 1 - t;
}
};
stackView.popEnterAnimation = new AnimationDescription
{
durationMs = 300,
easing = Easing.OutQuad,
callback = (element, t) =>
{
var offset = -50 * (1 - t);
element.style.translate = new Translate(new Length(offset, LengthUnit.Percent), 0);
element.style.opacity = 0.5f + t * 0.5f;
}
};

Clearing the stack. Resetting the stack to start fresh.

// Clear all items and reset to initial state
stackView.ClearStack();
// Then push a new initial item
stackView.Push(homeScreen);

Constructors

StackView()

The constructor of the StackView.

Declaration

public StackView()

Fields

ussClassName

The main styling class of the StackView. This is the class that is used in the USS file.

Declaration

public const string ussClassName = "appui-stackview"

Field Value

Type	Description
string

Properties

currentItem

The current item in the stack.

Declaration

public StackViewItem currentItem { get; }

Property Value

Type	Description
StackViewItem

depth

The depth of the stack.

Declaration

public int depth { get; }

Property Value

Type	Description
int

initialItem

The initial item to add to the stack.

Declaration

public VisualElement initialItem { get; set; }

Property Value

Type	Description
VisualElement

isBusy

Check if the StackView has any active animation.

Declaration

public bool isBusy { get; }

Property Value

Type	Description
bool

isEmpty

Check if the stack is empty.

Declaration

public bool isEmpty { get; }

Property Value

Type	Description
bool

popEnterAnimation

The animation to use on the newly active item when an item is popped from the stack.

Declaration

public AnimationDescription popEnterAnimation { get; set; }

Property Value

Type	Description
AnimationDescription

popExitAnimation

The animation to use on the current item when it is popped from the stack.

Declaration

public AnimationDescription popExitAnimation { get; set; }

Property Value

Type	Description
AnimationDescription

pushEnterAnimation

The animation to use on the newly active item when it is pushed to the stack.

Declaration

public AnimationDescription pushEnterAnimation { get; set; }

Property Value

Type	Description
AnimationDescription

pushExitAnimation

The animation to use on the current item when a new item is pushed to the stack.

Declaration

public AnimationDescription pushExitAnimation { get; set; }

Property Value

Type	Description
AnimationDescription

replaceEnterAnimation

The animation to use on the newly active item when it is replaced in the stack.

Declaration

public AnimationDescription replaceEnterAnimation { get; set; }

Property Value

Type	Description
AnimationDescription

replaceExitAnimation

The animation to use on the current item when it is replaced in the stack.

Declaration

public AnimationDescription replaceExitAnimation { get; set; }

Property Value

Type	Description
AnimationDescription

Methods

ClearStack()

Removes all items from the stack.

Declaration

public void ClearStack()

Pop(StackViewItem, StackViewOperation)

Pops one or more items off the stack.

Declaration

public StackViewItem Pop(StackViewItem item, StackViewOperation operation = StackViewOperation.PopTransition)

Parameters

Type	Name	Description
StackViewItem	item	If the item argument is specified, all items down to (but not including) item will be popped. If item is null, all items down to (but not including) the first item is popped.
StackViewOperation	operation	The type of transition to use during the process.

Returns

Type	Description
StackViewItem	Returns the last item removed from the stack.

Pop(StackViewOperation)

Pops one or more items off the stack. Only the current item is popped.

Declaration

public StackViewItem Pop(StackViewOperation operation = StackViewOperation.PopTransition)

Parameters

Type	Name	Description
StackViewOperation	operation	The type of transition to use during the process.

Returns

Type	Description
StackViewItem	Returns the last item removed from the stack.

Push(VisualElement, Action, StackViewOperation)

Pushes an item onto the stack using an optional operation.

Declaration

public StackViewItem Push(VisualElement item, Action callback = null, StackViewOperation operation = StackViewOperation.PushTransition)

Parameters

Type	Name	Description
VisualElement	item	The item to push onto the stack.
Action	callback	The callback to call when the operation is completed.
StackViewOperation	operation	The type of transition to use during the process.

Returns

Type	Description
StackViewItem	Returns the item that became current.

Replace(StackViewItem, VisualElement, Action, StackViewOperation)

Replaces one or more items on the stack with the specified item and optional operation.

Declaration

public StackViewItem Replace(StackViewItem target, VisualElement item, Action callback = null, StackViewOperation operation = StackViewOperation.ReplaceTransition)

Parameters

Type	Name	Description
StackViewItem	target	If the target argument is specified, all items down to the target item will be replaced. If target is null, all items in the stack will be replaced.
VisualElement	item	The item that will be used as replacement.
Action	callback	The callback to call when the operation is completed.
StackViewOperation	operation	The type of transition to use during the process.