diff --git a/docs/maui/TOC.yml b/docs/maui/TOC.yml
index 7582d625..8e7ed25d 100644
--- a/docs/maui/TOC.yml
+++ b/docs/maui/TOC.yml
@@ -243,6 +243,10 @@ items:
           href: views/Popup.md
         - name: "Popup Service"
           href: views/popup-service.md
+        - name: "Customizing Popup behavior and appearance"
+          href: views/popup/popup-options.md
+        - name: "Returning a value from a Popup"
+          href: views/popup/popup-result.md
     - name: SemanticOrderView
       href: views/semantic-order-view.md
 - name: C# Markup
diff --git a/docs/maui/images/views/popup/popup-blue-border.png b/docs/maui/images/views/popup/popup-blue-border.png
new file mode 100644
index 00000000..524b8a8c
Binary files /dev/null and b/docs/maui/images/views/popup/popup-blue-border.png differ
diff --git a/docs/maui/images/views/popup/popup-green-shadow.png b/docs/maui/images/views/popup/popup-green-shadow.png
new file mode 100644
index 00000000..2c78a826
Binary files /dev/null and b/docs/maui/images/views/popup/popup-green-shadow.png differ
diff --git a/docs/maui/images/views/popup/popup-no-border.png b/docs/maui/images/views/popup/popup-no-border.png
new file mode 100644
index 00000000..57352bd0
Binary files /dev/null and b/docs/maui/images/views/popup/popup-no-border.png differ
diff --git a/docs/maui/images/views/popup/popup-no-shadow.png b/docs/maui/images/views/popup/popup-no-shadow.png
new file mode 100644
index 00000000..52cb1222
Binary files /dev/null and b/docs/maui/images/views/popup/popup-no-shadow.png differ
diff --git a/docs/maui/images/views/popup/popup-page-overlay-opaque.png b/docs/maui/images/views/popup/popup-page-overlay-opaque.png
new file mode 100644
index 00000000..16c33ffd
Binary files /dev/null and b/docs/maui/images/views/popup/popup-page-overlay-opaque.png differ
diff --git a/docs/maui/images/views/popup/popup-page-overlay-translucent.png b/docs/maui/images/views/popup/popup-page-overlay-translucent.png
new file mode 100644
index 00000000..d92dbd5a
Binary files /dev/null and b/docs/maui/images/views/popup/popup-page-overlay-translucent.png differ
diff --git a/docs/maui/images/views/popup/popup-result.png b/docs/maui/images/views/popup/popup-result.png
new file mode 100644
index 00000000..b546ba2f
Binary files /dev/null and b/docs/maui/images/views/popup/popup-result.png differ
diff --git a/docs/maui/images/views/popup/popup-with-button.png b/docs/maui/images/views/popup/popup-with-button.png
new file mode 100644
index 00000000..dead16bb
Binary files /dev/null and b/docs/maui/images/views/popup/popup-with-button.png differ
diff --git a/docs/maui/images/views/popup/popup-with-padding.png b/docs/maui/images/views/popup/popup-with-padding.png
new file mode 100644
index 00000000..94d0e696
Binary files /dev/null and b/docs/maui/images/views/popup/popup-with-padding.png differ
diff --git a/docs/maui/views/Popup.md b/docs/maui/views/Popup.md
index d42505f0..b3b49a61 100644
--- a/docs/maui/views/Popup.md
+++ b/docs/maui/views/Popup.md
@@ -7,282 +7,182 @@ ms.date: 04/12/2022
 
 # Popup
 
-Popups are a very common way of presenting information to a user that relates to their current task. Operating systems provide a way to show a message and require a response from the user, these alerts are typically restrictive in terms of the content a developer can provide and also the layout and appearance.
+Popups are a common way of presenting information to a user that relates to their current task. Operating systems provide a way to show a message and require a response from the user, these alerts are typically restrictive in terms of the content a developer can provide and also the layout and appearance.
 
 > [!NOTE]
 > If you wish to present something to the user that is more subtle then checkout our [Toast](../alerts/toast.md) and [Snackbar](../alerts/snackbar.md) options.
 
 The `Popup` view allows developers to build their own custom UI and present it to their users.
 
-## Building a Popup
+The .NET MAUI Community Toolkit provides 2 approaches to create a `Popup` that can be shown in a .NET MAUI application. These approaches will depend on the use case. This page focuses on the simplest form of `Popup` - simply rendering an overlay in an application. For a more advanced approach, enabling the ability to return a result from the `Popup`, please refer to [Popup - Returning a result](./popup/popup-result.md).
 
-A `Popup` can be created in XAML or C#:
+## Displaying a Popup
 
-### XAML
+The .NET MAUI Community Toolkit provides multiple approaches to display a `Popup` in a .NET MAUI application:
 
-#### Including the XAML namespace
+1. In a `ContentPage`, call to the `this.ShowPopupAsync()` extension method, passing in a `View` to display in the Popup
+    - **Note:** To further customize a Popup, please refer to the [**PopupOptions** documentation](./popup/popup-options.md).
+2. Returning a result from the `Popup`
+    - Please refer to the [**Popup - Returning a result** documentation](./popup/popup-result.md).
+3. Using the `PopupService`
+    - Please refer to the [**PopupService** documentation](./popup-service.md).
 
-[!INCLUDE [XAML usage guidance](../includes/xaml-usage.md)]
+The documentation below demonstrates the simplest way to display a Popup using the `.ShowPopupAsync()` extension method. This method returns a `Task<IPopupResult>` that will complete when the Popup closes. The `PopupOptions` provided are optional.
 
-#### Defining your Popup
-
-Please note that if a `Popup` is created in XAML it must have a C# code behind file as well. To understand why this is required please refer to this [.NET MAUI documentation page](/dotnet/maui/xaml/runtime-load).
-
-The easiest way to create a `Popup` is to add a new `.NET MAUI ContentView (XAML)` to your project and then change each of the files to the following:
-
-```xaml
-<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
-               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
-               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
-               x:Class="MyProject.SimplePopup">
-
-    <VerticalStackLayout>
-        <Label Text="This is a very important message!" />
-    </VerticalStackLayout>
-    
-</toolkit:Popup>
-```
-
-```csharp
-public partial class SimplePopup : Popup
+```cs
+public class MainPage : ContentPage
 {
-    public SimplePopup()
-    {
-        InitializeComponent();
-    }
-}
-```
-
-> [!IMPORTANT]
-> If the code behind file is not created along with the call to `InitializeComponent` then an exception will be thrown when trying to display your `Popup`.
-
-### C#
-
-```csharp
-using CommunityToolkit.Maui.Views;
+    // ...
 
-var popup = new Popup
-{
-    Content = new VerticalStackLayout
+    async void DisplayPopupButtonClicked(object? sender, EventArgs e)
     {
-        Children = 
+        await this.ShowPopupAsync(new Label
         {
-            new Label
+            Text = "This is a very important message!"
+        }, new PopupOptions
+        {
+            CanBeDismissedByTappingOutsideOfPopup = false,
+            Shape = new RoundRectangle
             {
-                Text = "This is a very important message!"
+                CornerRadius = new CornerRadius(20, 20, 20, 20),
+                StrokeThickness = 2,
+                Stroke = Colors.LightGray
             }
-        }
-    }
-};
-```
-
-## Presenting a Popup
-
-Once the `Popup` has been built it can then be presented through the use of our `Popup` extension methods or through the [`IPopupService`](popup-service.md) implementation from this toolkit.
+        })
 
-> [!IMPORTANT]
-> A `Popup` can only be displayed from a `Page` or an implementation inheriting from `Page`.
-
-```csharp
-using CommunityToolkit.Maui.Views;
-
-public class MyPage : ContentPage
-{
-    public void DisplayPopup()
-    {
-        var popup = new SimplePopup();
+        /**** Alternatively, Shell.Current can be used to display a Popup
 
-        this.ShowPopup(popup);
+        await Shell.Current.ShowPopupAsync(new Label
+        {
+            Text = "This is a very important message!"
+        }, new PopupOptions
+        {
+            CanBeDismissedByTappingOutsideOfPopup = false,
+            Shape = new RoundRectangle
+            {
+                CornerRadius = new CornerRadius(20, 20, 20, 20),
+                StrokeThickness = 2,
+                Stroke = Colors.LightGray
+            }
+        })
+        ****/
     }
 }
 ```
 
-## Closing a Popup
+![Popup with padding](../images/views/popup/popup-with-padding.png "Popup rendering with padding around a simple label")
 
-There are 2 different ways that a `Popup` can be closed; programmatically or by tapping outside of the popup.
+Alternatively, a `Popup` can be created in XAML or C# and passed into `ShowPopupAsync()`.
 
-### Programmatically closing a Popup
+### Building a Popup in XAML
 
-In order to close a `Popup` a developer must call `Close` or `CloseAsync` on the `Popup` itself. This is typically performed by responding to a button press from a user.
+The easiest way to create a `Popup` is to add a new `.NET MAUI ContentView (XAML)` to your project. This will create 2 files: a _*.xaml_ file and a _*.xaml.cs_ file. 
 
-We can enhance the previous XAML example by adding an **OK** `Button`:
+Replace the contents of _*.xaml_ with the following:
 
-```xml
-<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
-               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
-               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
-               x:Class="MyProject.SimplePopup">
+```xaml
+<ContentView
+    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
+    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
+    x:Class="MyProject.SimplePopup"
+    Padding="10">
 
-    <VerticalStackLayout>
-        <Label Text="This is a very important message!" />
-        <Button Text="OK" 
-                Clicked="OnOKButtonClicked" />
-    </VerticalStackLayout>
+    <Label Text="This is a very important message!" />
     
-</toolkit:Popup>
+</ContentView>
 ```
 
-In the resulting event handler we call `Close`, this will programmatically close the `Popup`.
+The default values for `HorizontalOptions` and `VerticalOptions` will result in the `Popup` being displayed in the center of page that it overlays.
 
-> [!NOTE]
-> `Close()` is a fire-and-forget method. It will complete and return to the calling thread before the operating system has dismissed the `Popup` from the screen. If you need to pause the execution of your code until the operating system has dismissed the `Popup` from the screen, use instead `CloseAsync()`.
+A popup will present with a default `Padding` of 15. In order to make the `SimplePopup` look better a `Padding` of 10 has been added.
 
-```csharp
-public partial class MySimplePopup : Popup
-{
-    // ...
+### Presenting a Popup Created in XAML
 
-    void OnOKButtonClicked(object? sender, EventArgs e) => Close();
-}
-```
+Once the `Popup` has been created in XAML, it can then be presented through the use of the `Popup` extension methods used on a `Page`, `Shell` or an `INavigation`, or through the [`IPopupService`](popup-service.md) implementation from this toolkit.
 
-In the resulting event handler we call `CloseAsync`, this will programmatically close the `Popup` allowing the caller to `await` the method until the operating system has dismissed the `Popup` from the screen.
+The following example shows how to instantiate and show the `SimplePopup` created in the previous example through an extension method on a `ContentPage`.
 
 ```csharp
-public partial class MySimplePopup : Popup
-{
-    // ...
+using CommunityToolkit.Maui.Views;
 
-    async void OnOKButtonClicked(object? sender, EventArgs e) 
+public class MyPage : ContentPage
+{
+    public async Task DisplayPopup(CancellationToken token)
     {
-        var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
+        var popup = new SimplePopup();
 
-         await CloseAsync(token: cts.Token);
-         await Toast.Make("Popup Dismissed By Button").Show();
+        await this.ShowPopupAsync(popup, PopupOptions.Empty, token);
     }
 }
 ```
 
-### Tapping outside of the Popup
-
-By default a user can tap outside of the `Popup` to dismiss it. This can be controlled through the use of the `CanBeDismissedByTappingOutsideOfPopup` property. Setting this property to `false` will prevent a user from being able to dismiss the `Popup` by tapping outside of it.
-
-## Returning a result
-
-A developer will quite often seek a response from their user, the `Popup` view allows developers to return a result that can be awaited for and acted on.
+![Popup with padding](../images/views/popup/popup-with-padding.png "Popup rendering with padding around a simple label")
 
-We can enhance our original XAML example to show how this can be accomplished:
-
-### XAML
-
-By adding 2 new buttons to the XAML:
+## Closing a Popup
 
-```xml
-<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
-               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
-               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
-               x:Class="MyProject.SimplePopup">
+There are 2 different ways that a `Popup` can be closed: 
 
-    <VerticalStackLayout>
-        <Label Text="This is a very important message! Do you agree?" />
-        <Button Text="Yes" 
-                Clicked="OnYesButtonClicked" />
-        <Button Text="No"
-                Clicked="OnNoButtonClicked" />
-    </VerticalStackLayout>
-    
-</toolkit:Popup>
-```
+1. A Popup can be closed programmatically 
+2. A Popup can be closed when a user taps outside of the popup
+    - **Note** To prevent a Popup from closing when a user taps outside of it, set `PopupOptions.CanBeDismissedByTappingOutsideOfPopup` to `false`
 
-Then adding the following event handlers in the C#:
+### 1. Programmatically closing a Popup
 
-```csharp
-async void OnYesButtonClicked(object? sender, EventArgs e)
-{
-    var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
-    await CloseAsync(true, cts.Token);
-}
+There are 3 options to close a `Popup` programatically:
 
-async void OnNoButtonClicked(object? sender, EventArgs e)
-{
-    var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
-    await CloseAsync(false, cts.Token);
-}
-```
+1. In a `ContentPage`, use the `this.ClosePopupAsync()` extension method
+2. In an app using `Shell`, use `Shell.Current.ClosePopupAsync()` extension method
+3. Use the `PopupService`
+    - Please refer to the [**PopupService** documentation](./popup-service.md).
 
-The `Close` method allows for an `object` value to be supplied, this will be the resulting return value. In order to await the result the `ShowPopupAsync` method must be used as follows:
+In the example below, we demonstrate how to use `this.ClosePopupAsync()` in a `ContentPage`. To learn how to use `PopupService` to close a Popup, please refer to the [**PopupService** documentation](./popup-service.md). 
 
 ```csharp
 using CommunityToolkit.Maui.Views;
 
 public class MyPage : ContentPage
 {
-    public async Task DisplayPopup()
+    public async Task DisplayAutomaticallyClosingPopup(Timespan displayTimeSpan, CancellationToken token)
     {
         var popup = new SimplePopup();
 
-        var result = await this.ShowPopupAsync(popup, CancellationToken.None);
-
-        if (result is bool boolResult)
+        // This Popup is closed programmatically after 2 seconds
+        this.ShowPopup(popup, new PopupOptions
         {
-            if (boolResult)
-            {
-                // Yes was tapped
-            }
-            else
-            {
-                // No was tapped
-            }
-        }
-    }
-}
-```
+            CanBeDismissedByTappingOutsideOfPopup = false
+        });
 
-> [!NOTE]
-> In order to handle the tapping outside of a `Popup` when also awaiting the result you can change the value that is returned through the `ResultWhenUserTapsOutsideOfPopup` property.
+        await Task.Delay(TimeSpan.FromSeconds(displayTimeSpan), token);
 
-## Styling
+        await this.ClosePopupAsync(token);
 
-The `Popup` class allows the use of .NET MAUI [Styles](/dotnet/maui/user-interface/styles/xaml) to make it easier to share common visual settings across multiple popups.
+        /**** Alternatively, Shell.Current can be used to close a Popup
+        Shell.Current.ShowPopup(popup, new PopupOptions
+        {
+            CanBeDismissedByTappingOutsideOfPopup = false
+        });
 
-The following example shows how to define a style that applies to the `SimplePopup` example from the previous section.
+        await Task.Delay(TimeSpan.FromSeconds(displayTimeSpan), token);
 
-```xaml
-<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
-               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
-               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
-               xmlns:popups="clr-namespace:CommunityToolkit.Maui.Sample.Views.Popups"
-               x:Class="MyProject.SimplePopup">
-
-    <toolkit:Popup.Resources>
-        <Style TargetType="{x:Type popups:SimplePopup}">
-            <Setter Property="Size" Value="100,200" />
-            <Setter Property="Color" Value="Green" />
-            <Setter Property="HorizontalOptions" Value="Center" />
-            <Setter Property="VerticalOptions" Value="Start" />
-            <Setter Property="CanBeDismissedByTappingOutsideOfPopup" Value="True" />
-        </Style>
-    </toolkit:Popup.Resources>
-
-    <VerticalStackLayout>
-        <Label Text="This is a very important message! Do you agree?" />
-        <Button Text="Yes" 
-                Clicked="OnYesButtonClicked" />
-        <Button Text="No"
-                Clicked="OnNoButtonClicked" />
-    </VerticalStackLayout>
-    
-</toolkit:Popup>
+        await Shell.Current.ClosePopupAsync(token);
+        ***/
+
+    }
+}
 ```
 
-> [!NOTE]
-> When creating a `Style` that targets `Popup` and you wish to make it apply to custom popups like the `SimplePopup` example, make sure to set the [`ApplyToDerivedTypes`](/dotnet/api/microsoft.maui.controls.style.applytoderivedtypes) property on the `Style` definition.
+### 2. Tapping outside of the Popup
+
+By default a user can tap outside of the `Popup` to dismiss it. This can be controlled through the use of the `PopupOptions.CanBeDismissedByTappingOutsideOfPopup` property. Setting this property to `false` will prevent a user from being able to dismiss the `Popup` by tapping outside of it. See [PopupOptions](./popup/popup-options.md) for more details.
 
-## Properties
+## PopupOptions
 
-|Property  |Type  |Description  |
-|---------|---------|---------|
-| `Anchor` | `View` | Gets or sets the `View` anchor. The Anchor is where the Popup will render closest to. When an Anchor is configured the popup will appear centered over that control or as close as possible. |
-| `CanBeDismissedByTappingOutsideOfPopup` | `bool` | Gets or sets a value indicating whether the popup can be dismissed by tapping outside of the Popup. On Android - when false the hardware back button is disabled. |
-| `Color` | `Color` | Gets or sets the `Color` of the Popup. This color sets the native background color of the `Popup`, which is independent of any background color configured in the actual `Content`. |
-| `Content` | `View` | Gets or sets the `View` content to render in the `Popup`. |
-| `HorizontalOptions` | `LayoutAlignment` | Gets or sets the `LayoutAlignment` for positioning the `Popup` horizontally on the screen. |
-| `Result` | `Task<object?>` | Gets the final result of the dismissed `Popup`. |
-| `Size` | `Size` | Gets or sets the `Size` of the Popup Display. The Popup will always try to constrain the actual size of the `Popup` to the size of the View unless a `Size` is specified. If the `Popup` uses the `HorizontalOptions` or `VerticalOptions` properties that are not the defaults then this `Size` property is required. |
-| `VerticalOptions` | `LayoutAlignment` | Gets or sets the `LayoutAlignment` for positioning the `Popup` vertically on the screen. |
+The `PageOverlayColor`, `Shape`, `Shadow` can all be customized for Popup. See [PopupOptions](./popup/popup-options.md) for more details.
 
 ## Events
 
+The `Popup` class provides the following events that can be subscribed to.
+
 |Event | Description  |
 |---------|---------|
 | `Closed` | Occurs when the `Popup` is closed. |
@@ -290,8 +190,14 @@ The following example shows how to define a style that applies to the `SimplePop
 
 ## Examples
 
-You can find an example of this feature in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Views/).
+You can find an example of this feature in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/).
 
 ## API
 
 You can find the source code for `Popup` over on the [.NET MAUI Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Maui/tree/main/src/CommunityToolkit.Maui/Views/Popup).
+
+## Additional Resources
+
+- [`IPopupService`](popup-service.md)
+- [`Popup` - Returning a result](./popup/popup-result.md)
+- [`PopupOptions` - Customizing a `Popup` behavior and appearance](./popup/popup-options.md)
\ No newline at end of file
diff --git a/docs/maui/views/popup-service.md b/docs/maui/views/popup-service.md
index b4cfe1e2..bb429ccd 100644
--- a/docs/maui/views/popup-service.md
+++ b/docs/maui/views/popup-service.md
@@ -13,17 +13,20 @@ The following sections will incrementally build on how to use the `PopupService`
 
 ## Creating a Popup
 
-In order to use the `PopupService` to present or close a `Popup` the `Popup` must first be registered. Based on the steps in [Defining your popup](./Popup.md#defining-your-popup) the following can be created.
+In order to use the `PopupService` to present or close a `Popup` the `Popup` must first be registered. Based on the steps in [Displaying a Popup](./Popup.md#displaying-a-popup) the following can be created.
 
 The XAML contents of the `Popup` can be defined as:
 
 ```xaml
-<toolkit:Popup 
+<ContentView
     xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
     xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
-    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
     xmlns:viewModels="clr-namespace:MyProject.ViewModels"
     x:Class="MyProject.Popups.NamePopup"
+    HorizontalOptions="Center"
+    VerticalOptions="Center"
+    Padding="10"
+    Spacing="6"
     x:DataType="viewModels:NamePopupViewModel">
 
     <VerticalStackLayout>
@@ -34,18 +37,17 @@ The XAML contents of the `Popup` can be defined as:
         <Button Text="Cancel" Command="{Binding CancelCommand}" />
     </VerticalStackLayout>
     
-</toolkit:Popup>
+</ContentView>
 ```
 
 The C# contents of the `Popup` can be defined as:
 
 ```csharp
-using CommunityToolkit.Maui.Views;
 using MyProject.ViewModels;
 
 namespace MyProject.Popups;
 
-public partial class NamePopup : Popup
+public partial class NamePopup : ContentView
 {
     public NamePopup(NamePopupViewModel namePopupViewModel)
     {
@@ -61,7 +63,7 @@ The backing view model for the `Popup` can be defined as:
 public class NamePopupViewModel : ObservableObject
 {
     [ObservableProperty]
-    string name = "";
+    public partial string Name { get; set; } = string.Empty;
 
     readonly IPopupService popupService;
 
@@ -97,7 +99,7 @@ builder.Services.AddTransientPopup<NamePopup, NamePopupViewModel>();
 
 The .NET MAUI Community Toolkit provides a mechanism to instantiate and present popups in a .NET MAUI application. The popup service is automatically registered with the `MauiAppBuilder` when using the `UseMauiCommunityToolkit` initialization method. This enables you to resolve an `IPopupService` implementation in any part of your application.
 
-The `IPopupService` makes it possible to register a popup view and its associated view model. The ability to show a `Popup` can now be driven by only providing the view model making it possible to keep a clean separation between view and view model.
+The `IPopupService` makes it possible to register a popup view and its associated view model. The ability to show a `Popup` requires a developer to pass in the current `INavigation` implementation for the current window in the application. The easiest way to achieve this is through the following example.
 
 The following example shows how to use the `IPopupService` to create and display a popup in a .NET MAUI application:
 
@@ -113,7 +115,7 @@ public class MyViewModel : INotifyPropertyChanged
 
     public void DisplayPopup()
     {
-        this.popupService.ShowPopup<NamePopupViewModel>();
+        this.popupService.ShowPopup<NamePopupViewModel>(Shell.Current);
     }
 }
 ```
@@ -121,9 +123,9 @@ public class MyViewModel : INotifyPropertyChanged
 Alternatively the caller can await the ShowPopupAsync method in order to handle a [result being returned](#returning-a-result). The `DisplayPopup` method can be rewritten as:
 
 ```csharp
-public void DisplayPopup()
+public async Task DisplayPopup()
 {
-    var name = await this.popupService.ShowPopupAsync<NamePopupViewModel>();
+    var result = await this.popupService.ShowPopupAsync<NamePopupViewModel>(currentPage.Navigation);
 }
 ```
 
@@ -133,9 +135,24 @@ The `IPopupService` also provides methods to handle a result being returned from
 
 ## Passing data to a Popup view model
 
-When presenting a Popup we sometimes need to pass data across to the underlying view model to allow for dynamic content to be presented to the user. The `IPopupService` makes this possible through the overloads of the `ShowPopup` and `ShowPopupAsync` methods that takes a `Action<TViewModel> onPresenting` parameter. This parameter has been designed to be framework agnostic and allow you as a developer to drive the loading/passing of data however best fits your architecture.
+When presenting a Popup we sometimes need to pass data across to the underlying view model to allow for dynamic content to be presented to the user. `IPopupService` makes this possible through the overloads of the `ShowPopup` and `ShowPopupAsync` methods that takes a `IDictionary<string, object> shellParameters` parameter. This makes use of the `IQueryAttributable` interface provided with .NET MAUI Shell, for more information on using this please refer to [Process navigation data using a single method](/dotnet/maui/fundamentals/shell/navigation#process-navigation-data-using-a-single-method).
 
-To extend the previous example of showing a `NamePopupViewModel` and its associated Popup, we can use the `onPresenting` parameter to pass in the users name:
+To extend the previous example of showing a `NamePopupViewModel` and its associated Popup, we can extend the `NamePopupViewModel` to implement the `IQueryAttributable` interface as follows:
+
+```csharp
+public class NamePopupViewModel : ObservableObject, IQueryAttributable
+{
+    [ObservableProperty]
+    public partial string Name { get; set; } = "";
+
+    public void ApplyQueryAttributes(IDictionary<string, object> query)
+    {
+        Name = (string)query[nameof(NamePopupViewModel.Name)];
+    }
+}
+```
+
+Then the view model that presents the popup and passes the data can look as follows:
 
 ```csharp
 public class MyViewModel : INotifyPropertyChanged
@@ -147,16 +164,24 @@ public class MyViewModel : INotifyPropertyChanged
         this.popupService = popupService;
     }
 
-    public void DisplayPopup()
+    public async Task DisplayPopup()
     {
-        this.popupService.ShowPopup<UpdatingPopupViewModel>(onPresenting: viewModel => viewModel.Name = "Shaun");
+        var queryAttributes = new Dictionary<string, object>
+        {
+            [nameof(NamePopupViewModel.Name)] = "Shaun"
+        };
+
+        await this.popupService.ShowPopupAsync<NamePopupViewModel>(
+            Shell.Current,
+            options: PopupOptions.Empty,
+            shellParameters: queryAttributes);
     }
 }
 ```
 
 ## Closing a Popup
 
-The `PopupService` provides the `ClosePopup` and `ClosePopupAsync` methods that make it possible to close a `Popup` from a view model.
+The `PopupService` provides the `ClosePopupAsync` method that makes it possible to close a `Popup` from a view model.
 
 ### Programmatically closing a Popup
 
@@ -164,9 +189,9 @@ Expanding on the previous example the following implementation can be added to t
 
 ```csharp
 [RelayCommand]
-void OnCancel()
+async Task OnCancel()
 {
-    popupService.ClosePopup();
+    await popupService.ClosePopupAsync(Shell.Current);
 }
 ```
 
@@ -180,13 +205,13 @@ Expanding on the previous example the following implementation can be added to t
 
 ```csharp
 [RelayCommand(CanExecute = nameof(CanSave))]
-void OnSave()
+async Task OnSave()
 {
-    popupService.ClosePopup(Name);
+    await popupService.ClosePopupAsync(Shell.Current, Name);
 }
 ```
 
-This will result in the most recently displayed `Popup` being closed and the caller being return the value in `Name`.
+This will result in the most recently displayed `Popup` being closed and the caller being return the value in `Name` wrapped inside of an `IPopupResult<T>` implementation. For more information on creating a `Popup` that can return a result see [`Popup` - Returning a result](./popup/popup-result.md).
 
 ## Examples
 
@@ -195,3 +220,9 @@ You can find an example of this feature in action in the [.NET MAUI Community To
 ## API
 
 You can find the source code for `Popup` over on the [.NET MAUI Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Maui/tree/main/src/CommunityToolkit.Maui/Views/Popup).
+
+## Additional Resources
+
+- [`Popup` - Returning a result](./popup/popup-result.md)
+- [`IPopupService`](./popup-service.md)
+- [`PopupOptions` - Customizing a `Popup` behavior and appearance](./popup/popup-options.md)
diff --git a/docs/maui/views/popup/popup-options.md b/docs/maui/views/popup/popup-options.md
new file mode 100644
index 00000000..18006882
--- /dev/null
+++ b/docs/maui/views/popup/popup-options.md
@@ -0,0 +1,139 @@
+---
+title: PopupOptions - .NET MAUI Community Toolkit
+author: bijington
+description: The PopupOptions class provides the ability to customize the appearance and behavior of the Popup.
+ms.date: 05/19/2025
+---
+
+# PopupOptions - Customizing the popup behavior and appearance
+
+The `PopupOptions` class provides the ability to customize the appearance and behavior of the `Popup`.
+
+All of the examples in this page make use of the `SimplePopup` example that is covered at [`Popup`](../popup.md).
+
+## Controlling whether the user can dismiss the Popup
+
+`PopupOptions` provides the `CanBeDismissedByTappingOutsideOfPopup` property which can control the whether the user can tap or click outside of the Popup bounds to dismiss the currently displayed Popup. This is `true` by default. The following example shows how to prevent a user from being able to dismiss the Popup.
+
+```csharp
+await this.ShowPopupAsync(new SimplePopup(), new PopupOptions
+{
+    CanBeDismissedByTappingOutsideOfPopup = false
+});
+```
+
+> [!NOTE]
+> It is possible to cache `PopupOptions` to reuse on future navigation actions or with other popups that share the same configuration, that would prevent unnecessary allocations.
+
+## Customize the Overlay Color
+
+`PopupOptions` provides the `PageOverlayColor` property which can control the `Color` that overlays the current page. The following example shows how to set the `PageOverlayColor` to orange.
+
+```csharp
+await this.ShowPopupAsync(new SimplePopup(), new PopupOptions
+{
+    PageOverlayColor = Colors.Orange
+});
+```
+
+![Popup page overlay](../../images/views/popup/popup-page-overlay-opaque.png "Popup rendering with an opaque orange background")
+
+The above `Popup` renders with an opaque background, to control the opacity modify the alpha property of a `Color`. The following example shows how to
+
+```csharp
+await this.ShowPopupAsync(new SimplePopup(), new PopupOptions
+{
+    PageOverlayColor = Colors.Orange.WithAlpha(0.5f)
+});
+```
+
+![Popup page transparent overlay](../../images/views/popup/popup-page-overlay-translucent.png "Popup rendering with a translucent orange background")
+
+## Customize the Popup Border
+
+`PopupOptions` provides the `Shape` property which can control the appearance of the border around the content displayed in the `Popup`. The following example shows how to set the border to be a rounded rectangle with a corner radius of 4 and a stroke of blue.
+
+```csharp
+await this.ShowPopupAsync(new SimplePopup(), new PopupOptions
+{
+    Shape = new RoundRectangle
+    {
+        CornerRadius = new CornerRadius(4),
+        Stroke = Colors.Blue,
+        StrokeThickness = 4
+    }
+});
+```
+
+![Popup blue border stroke](../../images/views/popup/popup-blue-border.png "Popup rendering with a blue border")
+
+For more details on how to customize the `Shape` property see [.NET MAUI Shapes](/dotnet/maui/user-interface/controls/shapes/).
+
+### Disable the Popup Border
+
+In order to disable the border on a Popup, simply set the `Shape` property to `null`. The following example shows how to achieve this
+
+```csharp
+await this.ShowPopupAsync(new SimplePopup(), new PopupOptions
+{
+    Shape = null
+});
+```
+
+![Popup no border](../../images/views/popup/popup-no-border.png "Popup rendering with no border")
+
+## Customize the Popup Shadow
+
+`PopupOptions` provides the `Shadow` property which can control the shadow which is applied to the `Popup`. The following example shows how to set the shadow to be green with an opacity of 80%.
+
+```csharp
+await this.ShowPopupAsync(new SimplePopup(), new PopupOptions
+{
+    Shadow = new Shadow
+    {
+        Brush = Brush.Green,
+        Opacity = 0.8f
+    }
+});
+```
+
+![Popup green shadow](../../images/views/popup/popup-green-shadow.png "Popup rendering with a green shadow")
+
+For more details on how to customize the `Shadow` property see [.NET MAUI Shadow](/dotnet/maui/user-interface/shadow).
+
+### Disable the Popup Shadow
+
+In order to disable the border on a Popup, simply set the `Shape` property to `null`. The following example shows how to achieve this
+
+```csharp
+await this.ShowPopupAsync(new SimplePopup(), new PopupOptions
+{
+    Shadow = null
+});
+```
+
+![Popup no shadow](../../images/views/popup/popup-no-shadow.png "Popup rendering with no shadow")
+
+## Properties
+
+|Property  |Type  |Description  |
+|---------|---------|---------|
+| `CanBeDismissedByTappingOutsideOfPopup` | `bool` | Gets or sets a value indicating whether the popup can be dismissed by tapping outside of the Popup. On Android - when false the hardware back button is disabled. |
+| `OnTappingOutsideOfPopup` | `Action` | Gets or sets the `Action` to be executed when the user taps outside the `Popup`. |
+| `PageOverlayColor` | `Color` | Gets or sets the `Color` of the overlay behind the `Popup`. |
+| `Shape` | `Shape` | Gets or sets the border shape for the `Popup`. Set this to `null` to remove any border styling. |
+| `Shadow` | `Shadow` | Gets or sets the `Shadow` of the `Popup`. Set this to `null` to remove any shadow. |
+
+## Examples
+
+You can find an example of this feature in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Views/Popups/ReturnResultPopup.xaml).
+
+## API
+
+You can find the source code for `PopupOptions` over on the [.NET MAUI Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Maui/tree/main/src/CommunityToolkit.Maui/Views/Popup).
+
+## Additional Resources
+
+- [`Popup`](../popup.md)
+- [`IPopupService`](../popup-service.md)
+- [`Popup` - Returning a result](./popup-result.md)
diff --git a/docs/maui/views/popup/popup-result.md b/docs/maui/views/popup/popup-result.md
new file mode 100644
index 00000000..e24aa6b3
--- /dev/null
+++ b/docs/maui/views/popup/popup-result.md
@@ -0,0 +1,179 @@
+---
+title: Popup<T> - .NET MAUI Community Toolkit
+author: bijington
+description: Popup<T> enables developers to return a value from a popup when it is dismissed.
+ms.date: 05/19/2025
+---
+
+# Returning a value from a Popup
+
+The .NET MAUI Community Toolkit provides the ability to show a [Popup](../Popup.md) to a user. The Toolkit also enables a common, more complex, scenario where a developer displays a `Popup` and `await` its result to be returned when that `Popup` is dismissed. This page covers how the `Popup<T>` class can be used to achieve the desired behavior.
+
+## Building a Popup
+
+A `Popup<T>` can be created in XAML or C# as follows:
+
+### Building a Popup in XAML
+
+The following section covers how to create a `Popup<T>` using XAML.
+
+#### Defining your Popup
+
+The easiest way to create a `Popup<T>` is to add a new `.NET MAUI ContentView (XAML)` to your project, this will create 2 files; a _*.xaml_ file and a _*.xaml.cs_ file. The contents of each file can be replaced with the following:
+
+##### XAML File
+
+```xaml
+<toolkit:Popup
+    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
+    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
+    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
+    Padding="10"
+    x:TypeArguments="system:Boolean"
+    x:Class="MyProject.ReturnResultPopup">
+
+    <VerticalStackLayout Spacing="6">
+        <Label Text="This is a very important message! Do you agree?" />
+
+        <Button Text="Yes" 
+                Clicked="OnYesButtonClicked" />
+
+        <Button Text="No"
+                Clicked="OnNoButtonClicked" />
+    
+    </VerticalStackLayout>
+    
+</toolkit:Popup>
+```
+
+The use of `x:TypeArguments` in XAML makes it possible to supply the type parameter for a generic type.
+
+##### XAML Code-Behind File
+
+```csharp
+public partial class ReturnResultPopup : Popup<bool>
+{
+    public ReturnResultPopup()
+    {
+        InitializeComponent();
+    }
+
+    async void OnYesButtonClicked(object? sender, EventArgs e)
+    {
+        await CloseAsync(true);
+    }
+    
+    async void OnNoButtonClicked(object? sender, EventArgs e)
+    {
+        await CloseAsync(false);
+    }
+}
+```
+
+The use of `Popup<bool>` must match the definition in the XAML through the use of `x:TypeArguments`.
+
+> [!IMPORTANT]
+> If the code behind file is not created along with the call to `InitializeComponent` then an exception will be thrown when trying to display your `Popup`.
+
+### Building a Popup in C#
+
+The following section covers how to create a `Popup` using C#.
+
+```csharp
+using CommunityToolkit.Maui.Views;
+
+namespace MyProject;
+
+public class ReturnResultPopup : Popup<bool>
+{
+    public ReturnResultPopup()
+    {
+        var yesButton = new Button { Text = "Yes" };
+        yesButton.Clicked += OnYesButtonClicked;
+
+        var noButton = new Button { Text = "No" };
+        noButton.Clicked += OnNoButtonClicked;
+
+        Content = new VerticalStackLayout
+        {
+            Children = 
+            {
+                new Label { Text = "This is a very important message! Do you agree?" },
+                
+                yesButton,
+                noButton
+            }
+        };
+    }
+
+    async void OnYesButtonClicked(object? sender, EventArgs e)
+    {
+        await CloseAsync(true);
+    }
+    
+    async void OnNoButtonClicked(object? sender, EventArgs e)
+    {
+        await CloseAsync(false);
+    }
+}
+```
+
+The `CloseAsync` method allows for a value to be supplied, this will be the resulting return value. The use of generics in `Popup<T>` provides type-safety when returning values from a Popup.
+
+## Awaiting the result from a Popup
+
+In order to await the result the `ShowPopupAsync` method must be used as follows:
+
+```csharp
+using CommunityToolkit.Maui.Views;
+
+public class MyPage : ContentPage
+{
+    public async Task DisplayPopup()
+    {
+        var popup = new ReturnResultPopup();
+
+        // The type parameter must match the type returned from the popup.
+        IPopupResult<bool> popupResult = await this.ShowPopupAsync(popup, CancellationToken.None);
+
+        if (popupResult.WasDismissedByTappingOutsideOfPopup)
+        {
+            return;
+        }
+
+        if (popupResult.Result is true)
+        {
+            // Yes was tapped
+        }
+        else
+        {
+            // No was tapped
+        }
+    }
+}
+```
+
+![Popup with result](../../images/views/popup/popup-result.png "Popup rendering with two buttons that allow for a result to be returned")
+
+> [!NOTE]
+> If `WasDismissedByTappingOutsideOfPopup` is `true` then the `Result` property will always be `null` or `default`.
+
+## PopupOptions
+The `PopupOptions` class provides the ability to customize the Border, Shadow, PageOverlayColor, and more, of the displayed `Popup`.
+
+Please refer to the [PopupOptions Documentation](./popup-options.md) to learn more.
+
+
+## Examples
+
+You can find an example of this feature in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Views/Popups/ReturnResultPopup.xaml).
+
+## API
+
+You can find the source code for `Popup` over on the [.NET MAUI Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Maui/tree/main/src/CommunityToolkit.Maui/Views/Popup).
+
+## Additional Resources
+
+- [`Popup`](../popup.md)
+- [`IPopupService`](../popup-service.md)
+- [`PopupOptions` - Customizing a `Popup` behavior and appearance](./popup-options.md)