# Overlay

> Overlays are persistent and customizable panels and toolbars that are available within Editor Windows. Use Overlays to expose actions and tool options in a convenient and user-controllable way.

## Definition

* **Type:** Class
* **Namespace:** [UnityEditor.Overlays](/engine/6000.3/script-reference/unityeditor/overlays.md)
* **Assembly:** UnityEditor

```csharp
public abstract class Overlay
```

## Remarks

This is the base class that all overlays inherit from. To create an overlay, return a [VisualElement](/engine/6000.3/script-reference/unityengine/uielements/visualelement.md).

The simplest way to display an overlay is to use [OverlayAttribute](/engine/6000.3/script-reference/unityeditor/overlays/overlayattribute.md) and register a target [EditorWindow](/engine/6000.3/script-reference/unityeditor/editorwindow.md).

```csharp
using UnityEditor;
using UnityEditor.Overlays;
using UnityEngine.UIElements;

// Specifying `OverlayAttribute.editorWindowType` tells the OverlayCanvas to always show this Overlay in the menu.
[Overlay(typeof(SceneView), "Selection Count")]
class SelectionCount : Overlay
{
    Label m_Label;

    public override VisualElement CreatePanelContent()
    {
        Selection.selectionChanged += () =>
        {
            if (m_Label != null)
                m_Label.text = $"Selection Count {Selection.count}";
        };

        return m_Label = new Label($"Selection Count {Selection.count}");
    }
}
```

Overlays can be used in any [EditorWindow](/engine/6000.3/script-reference/unityeditor/editorwindow.md) that implements [ISupportsOverlays](/engine/6000.3/script-reference/unityeditor/overlays/isupportsoverlays.md). You can use [OverlayCanvas.Add](/engine/6000.3/script-reference/unityeditor/overlays/overlaycanvas/add.md) and [OverlayCanvas.Remove](/engine/6000.3/script-reference/unityeditor/overlays/overlaycanvas/remove.md) to add and remove overlays from the Overlays menu.

```csharp
using System;
using UnityEditor;
using UnityEditor.Overlays;
using UnityEngine;
using UnityEngine.UIElements;

public class OverlayWindowExample : EditorWindow, ISupportsOverlays
{
    bool m_ShowOverlay;
    InstanceOverlay m_Overlay;

    // InstanceOverlay is not registered as a persistent overlay, and it must be instantiated through code. In contrast,
    // PersistentOverlay is registered with a target window type and will be available at any time.
    // All OverlayAttribute properties are optional. Here, we specify that when this overlay is added to a window for the
    // first time, so it is visible by default. If <c>defaultDisplay</c> is set to it's default value of false, the
    // Overlay will be available in the Overlay Menu when added to a window, but not visible.
    [Overlay(defaultDisplay = true)]
    class InstanceOverlay : Overlay
    {
        OverlayWindowExample m_Window;
        public InstanceOverlay(OverlayWindowExample win) => m_Window = win;
        public override VisualElement CreatePanelContent() => new Label() { text = $"Hello from {m_Window.name}!" };
    }

    // Persistent overlays are always available in the Overlay Menu. An Overlay is made persistent by assigning the
    // `editorWindowType` property in `OverlayAttribute`.
    [Overlay(typeof(OverlayWindowExample), "Persistent Overlay", defaultDisplay = true)]
    class PersistentOverlay : Overlay
    {
        public override VisualElement CreatePanelContent() => new Label() { text = "Hello, I'm always available!" };
    }

    [MenuItem("Window/Overlay Window")]
    static void Init() => GetWindow<OverlayWindowExample>();

    void OnEnable() => m_Overlay = new InstanceOverlay(this);

    void OnGUI()
    {
        EditorGUI.BeginChangeCheck();
        m_ShowOverlay = EditorGUILayout.Toggle("Show Overlay", m_ShowOverlay);
        if (EditorGUI.EndChangeCheck())
        {
            if (m_ShowOverlay)
                overlayCanvas.Add(m_Overlay);
            else
                overlayCanvas.Remove(m_Overlay);
        }
    }
}
```

Overlays can be shown in the active [SceneView](/engine/6000.3/script-reference/unityeditor/sceneview.md) through [SceneView.AddOverlayToActiveView](/engine/6000.3/script-reference/unityeditor/sceneview/addoverlaytoactiveview.md) and [SceneView.RemoveOverlayFromActiveView](/engine/6000.3/script-reference/unityeditor/sceneview/removeoverlayfromactiveview.md). This is useful for [EditorTool](/engine/6000.3/script-reference/unityeditor/editortools/editortool.md)s that need to show UI.

```csharp
using System.Linq;
using UnityEngine;
using UnityEditor;
using UnityEditor.EditorTools;
using UnityEditor.Overlays;
using UnityEngine.UIElements;

// A simple tool that moves the selected transforms using an Overlay interface.
[EditorTool("Offset", typeof(Transform))]
public class OffsetTool : EditorTool
{
    // By default, overlays added to the canvas are not displayed. Setting the `defaultDisplay` property ensures that the
    // first time this Overlay is added to a canvas it will be visible.
    [Overlay(defaultDisplay = true)]
    class OffsetToolOverlay : Overlay
    {
        Transform[] selection;

        public OffsetToolOverlay(Transform[] targets) => selection = targets;

        public override VisualElement CreatePanelContent()
        {
            var root = new VisualElement();
            root.Add(new Button(() => Move(Vector3.right)) { text = "Move Right" });
            root.Add(new Button(() => Move(Vector3.up)) { text = "Move Up" });
            root.Add(new Button(() => Move(Vector3.forward)) { text = "Move Forward" });
            return root;
        }

        void Move(Vector3 direction)
        {
            Undo.RecordObjects(selection, "Move Selection");
            foreach (var transform in selection)
                transform.position += direction;
        }
    }

    OffsetToolOverlay m_Overlay;

    public override void OnActivated()
    {
        SceneView.AddOverlayToActiveView(m_Overlay = new OffsetToolOverlay(targets.Select(x => x as Transform).ToArray()));
    }

    public override void OnWillBeDeactivated()
    {
        SceneView.RemoveOverlayFromActiveView(m_Overlay);
    }
}
```

To create an Overlay that is dockable in a toolbar, see [ToolbarOverlay](/engine/6000.3/script-reference/unityeditor/overlays/toolbaroverlay.md).

## Static Fields

| Value                                                                                        | Description                              |
| -------------------------------------------------------------------------------------------- | ---------------------------------------- |
| [ussClassName](/engine/6000.3/script-reference/unityeditor/overlays/overlay/ussclassname.md) | USS class name of elements of this type. |

## Properties

| Property                                                                                               | Description                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [activeLayout](/engine/6000.3/script-reference/unityeditor/overlays/overlay/activelayout.md)           | The layout that the system displays an [Overlay](/engine/6000.3/script-reference/unityeditor/overlays/overlay.md) in.                                        |
| [collapsed](/engine/6000.3/script-reference/unityeditor/overlays/overlay/collapsed.md)                 | Defines whether the overlay is in collapsed form.                                                                                                            |
| [collapsedIcon](/engine/6000.3/script-reference/unityeditor/overlays/overlay/collapsedicon.md)         | Defines a custom icon to use when that overlay is in collapsed form.                                                                                         |
| [containerWindow](/engine/6000.3/script-reference/unityeditor/overlays/overlay/containerwindow.md)     | EditorWindow the overlay is contained within.                                                                                                                |
| [defaultSize](/engine/6000.3/script-reference/unityeditor/overlays/overlay/defaultsize.md)             | Set defaultSize to define the size of an [Overlay](/engine/6000.3/script-reference/unityeditor/overlays/overlay.md) when it hasn't been resized by the user. |
| [displayed](/engine/6000.3/script-reference/unityeditor/overlays/overlay/displayed.md)                 | Shows or hides the overlay.                                                                                                                                  |
| [displayName](/engine/6000.3/script-reference/unityeditor/overlays/overlay/displayname.md)             | Name of overlay used as title.                                                                                                                               |
| [floating](/engine/6000.3/script-reference/unityeditor/overlays/overlay/floating.md)                   | Returns true if overlay is floating, returns false if overlay is docked in a corner or in a toolbar.                                                         |
| [floatingPosition](/engine/6000.3/script-reference/unityeditor/overlays/overlay/floatingposition.md)   | Local position of closest overlay corner to closest dockposition when floating.                                                                              |
| [id](/engine/6000.3/script-reference/unityeditor/overlays/overlay/id.md)                               | Overlay unique ID.                                                                                                                                           |
| [isInToolbar](/engine/6000.3/script-reference/unityeditor/overlays/overlay/isintoolbar.md)             | Returns true if overlay is docked in a toolbar.                                                                                                              |
| [layout](/engine/6000.3/script-reference/unityeditor/overlays/overlay/layout.md)                       | The preferred layout for the [Overlay](/engine/6000.3/script-reference/unityeditor/overlays/overlay.md).                                                     |
| [maxSize](/engine/6000.3/script-reference/unityeditor/overlays/overlay/maxsize.md)                     | Maximum size of the Overlay.                                                                                                                                 |
| [minSize](/engine/6000.3/script-reference/unityeditor/overlays/overlay/minsize.md)                     | Minimum size of the Overlay.                                                                                                                                 |
| [rootVisualElement](/engine/6000.3/script-reference/unityeditor/overlays/overlay/rootvisualelement.md) | The root [VisualElement](/engine/6000.3/script-reference/unityengine/uielements/visualelement.md).                                                           |
| [size](/engine/6000.3/script-reference/unityeditor/overlays/overlay/size.md)                           | Size of the Overlay.                                                                                                                                         |

## Methods

| Method                                                                                                   | Description                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Close](/engine/6000.3/script-reference/unityeditor/overlays/overlay/close.md)                           | Remove the [Overlay](/engine/6000.3/script-reference/unityeditor/overlays/overlay.md) from its [OverlayCanvas](/engine/6000.3/script-reference/unityeditor/overlays/overlaycanvas.md). |
| [CreateContent](/engine/6000.3/script-reference/unityeditor/overlays/overlay/createcontent.md)           | Creates a new VisualElement containing the contents of this Overlay.                                                                                                                   |
| [CreatePanelContent](/engine/6000.3/script-reference/unityeditor/overlays/overlay/createpanelcontent.md) | Implement this method to return your visual element content.                                                                                                                           |
| [OnCreated](/engine/6000.3/script-reference/unityeditor/overlays/overlay/oncreated.md)                   | OnCreated is invoked when an [Overlay](/engine/6000.3/script-reference/unityeditor/overlays/overlay.md) is instantiated in an Overlay Canvas.                                          |
| [OnWillBeDestroyed](/engine/6000.3/script-reference/unityeditor/overlays/overlay/onwillbedestroyed.md)   | Called when an [Overlay](/engine/6000.3/script-reference/unityeditor/overlays/overlay.md) is about to be destroyed.                                                                    |
| [RefreshPopup](/engine/6000.3/script-reference/unityeditor/overlays/overlay/refreshpopup.md)             | Resize the OverlayPopup to fit the content.                                                                                                                                            |
| [Undock](/engine/6000.3/script-reference/unityeditor/overlays/overlay/undock.md)                         | If this [Overlay](/engine/6000.3/script-reference/unityeditor/overlays/overlay.md) is currently in a toolbar, it will be removed and return to a floating state.                       |

## Events

| Member                                                                                                             | Description                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [collapsedChanged](/engine/6000.3/script-reference/unityeditor/overlays/overlay/collapsedchanged.md)               | Invoked when [Overlay.collapsed](/engine/6000.3/script-reference/unityeditor/overlays/overlay/collapsed.md) value is changed.                            |
| [displayedChanged](/engine/6000.3/script-reference/unityeditor/overlays/overlay/displayedchanged.md)               | This callback is invoked when the [Overlay.displayed](/engine/6000.3/script-reference/unityeditor/overlays/overlay/displayed.md) value has been changed. |
| [floatingChanged](/engine/6000.3/script-reference/unityeditor/overlays/overlay/floatingchanged.md)                 | Called when the value of floating has changed.                                                                                                           |
| [floatingPositionChanged](/engine/6000.3/script-reference/unityeditor/overlays/overlay/floatingpositionchanged.md) | This event is invoked when [Overlay.floatingPosition](/engine/6000.3/script-reference/unityeditor/overlays/overlay/floatingposition.md) is changed.      |
| [layoutChanged](/engine/6000.3/script-reference/unityeditor/overlays/overlay/layoutchanged.md)                     | Subscribe to this event to be notified when the [Layout](/engine/6000.3/script-reference/unityeditor/overlays/overlay/layout.md) property is modified.   |