1 of 68

Components

A Universal app website is composed of components. In addition to the core component, you can also extend Universal with a large set of community created components.

Additional components can be downloaded from the UD Marketplace.

External components are distributed as PowerShell modules and can be used in an app by using Import-Module.

When building an app, you can simply call the PowerShell cmdlets within your app script to create a new component.

New-UDApp -Title 'Dashboard' -Content {
    New-UDTypography -Text 'Hello, world!'
}

Adding Components to Apps

You can add component modules by clicking the Components button on the App page and then adding the components. This list will also include components downloaded from the Marketplace.

Manual Component Installation

You can manually install components into the assets folder by including the appropriate folder structure and files. All components need to be valid PowerShell modules.

Each component should be in a folder with the module name and an additional folder with the version.

Including Components in the Repository

You can also include components within the code Repository. By including them in the repository, they will be downloaded when using git sync. This functionality is only enabled when git sync is enabled.

After a git pull is performed on the remote repository, Components will be automatically loaded and available within the Components page within PowerShell Universal. The structure and layout of the components folder is the same as the main assets folder.

Pages

Information about Universal App pages.

An app can consist of one or more pages. A page can have a particular name and URL. You can define a URL that accepts one or more variables in the URL to define a dynamic page.

Creating a new page

Within the app editor, expand the Pages navigation menu and click New Page.

You can edit a page by clicking the link in the menu. The code editor will switch to the page's content.

To reference the page in your dashboard, use Get-UDPage.

Basic Page

A basic page can be defined using the New-UDPage cmdlet. You could navigate to this page by visiting the /appURL of your dashboard.

$Pages = @()
$Pages += New-UDPage -Name 'Dashboard' -Content {
    New-UDTypography -Text 'Dashboard'
}

New-UDApp -Title 'Pages' -Pages $Pages

App with Multiple Pages

Apps can have multiple pages and those pages can be defined by passing an array of UDPages to New-UDApp

$Pages = @()
$Pages += New-UDPage -Name 'App One' -Content {
    New-UDTypography -Text 'App Two'
}

$Pages += New-UDPage -Name 'App Two' -Content {
    New-UDTypography -Text 'App Two'
}

New-UDApp -Title 'Pages' -Pages $Pages

You may want to organize your app into multiple PS1 files. You can do this using pages.

$UDScriptRoot = $PSScriptRoot
$Pages = @()
$Pages += New-UDPage -Name 'App One' -Content {
    . "$UDScriptRoot\db1.ps1"
}

$Pages += New-UDPage -Name 'App Two' -Content {
    . "$UDScriptRoot\db2.ps1"
}

New-UDApp -Title 'Pages' -Pages $Pages

Page with a Custom URL

A page can have a custom URL by using the -Url parameter. You could navigate to this page by visiting the /db URL of your app.

$Pages = @()
$Pages += New-UDPage -Name 'App' -Url '/db' -Content {
    New-UDTypography -Text 'App'
}

New-UDApp -Title 'Pages' -Pages $Pages

Page with Variables in URL

You can define a page with variables in the URL to create pages that adapt based on that URL.

$Pages = @()
$Pages += New-UDPage -Name 'Dashboard' -Url '/db/:user' -Content {
    New-UDTypography -Text 'Dashboard for user: $User'
}

New-UDApp -Title 'Pages' -Pages $Pages

Query string parameters

Query string parameters are passed to pages and other endpoints as a hashtable variable called $Query.

For example, if you visited a page with the following query string parameter: http://localhost:5000/dashboard/Page1?test=123

You would have access to this value using the following syntax:

$Query.test
$Query['test']

Role-Based Access

This feature requires a license.

You can prevent users from accessing pages based on their role by using the -Role parameter of pages. You can configure roles and role policies on the Security page.

$Pages = @()
$Pages += New-UDPage -Name 'Administrators' -Content {
    New-UDTypography -Text 'Dashboard for user: $User'
} -Role 'Administrator'

$Pages += New-UDPage -Name 'Operators' -Content {
    New-UDTypography -Text 'Dashboard for user: $User'
} -Role 'Operator'

New-UDApp -Title 'Pages' -Pages $Pages

Header

The following options are available for customizing the header.

Position

Use the -HeaderPosition parameter to adjust the behavior of the header.

absolute\fixed - Remains at the top of the page, even when scrolling
relative - Remains at the top of the page. Not visible when scrolling.

New-UDPage -HeaderPosition fixed -Content {
    New-UDElement -tag div -Attributes @{
        style = @{
            height = '150vh'
        }
    }
}

Colors

You can adjust the colors of the header by specifying the -HeaderColor and -HeaderBackgroundColor parameters. These colors will override the theme colors.

New-UDPage -Name 'Home' -Content {
} -HeaderColor 'black' -HeaderBackgroundColor 'white'

You can customize the navigation of a page using the -Navigation and -NavigationLayout parameters. Navigation is defined using the List component. Navigation layouts are either permanent or temporary.

Custom navigation can be defined with a list. List items can include children to create drop down sections in the navigation.

$Navigation = @(
    New-UDListItem -Label "Home"
    New-UDListItem -Label "Getting Started" -Children {
        New-UDListItem -Label "Installation" -Href '/Installation' 
        New-UDListItem -Label "Usage" -Href '/Usage' 
        New-UDListItem -Label "FAQs" -Href '/faqs' 
        New-UDListItem -Label "System Requirements" -Href'/requirements' 
        New-UDListItem -Label "Purchasing" -Href '/purchasing' 
    }
)

$Pages = @()
$Pages += New-UDPage -Name 'Installation' -Content {
 New-UDTypography -Text "Installation"
}

$Pages += New-UDPage -Name 'Usage' -Content {
    New-UDTypography -Text "Usage"
} 

New-UDApp -Title "Hello, World!" -Pages $Pages -NavigationLayout permanent -Navigation $Navigation

Dynamic navigation can be used to execute scripts during page load to determine which navigation components to show based on variables like the user, IP address or roles.

You can generate dynamic navigation by using the -LoadNavigation parameter. The value of the parameter should be a script block to execute when loading the navigation.

$Navigation = {
    New-UDListItem -Label "Home - $(Get-Date)"
    New-UDListItem -Label "Getting Started" -Children {
        New-UDListItem -Label "Installation" -Href '/installation' 
        New-UDListItem -Label "Usage" -Href '/usage' 
        New-UDListItem -Label "FAQs" -Href '/faqs' 
        New-UDListItem -Label "System Requirements" -Href'/requirements' 
        New-UDListItem -Label "Purchasing" -Href '/purchasing' 
    }
}

$Pages = @()
$Pages += New-UDPage -Name 'Test' -Content {
 New-UDTypography -Text "Hello"
} -NavigationLayout permanent -LoadNavigation $Navigation

$Pages += New-UDPage -Name 'Test2' -Content {
    New-UDTypography -Text "Hello"
} -NavigationLayout permanent -LoadNavigation $Navigation


New-UDApp -Title "Hello, World!" -Pages $Pages

Layouts

The permanent layout creates a static navigation drawer on the left hand side of the page. It cannot be hidden by the user.

$Pages = @()
$Pages += New-UDPage -Name 'Test' -Content {
 New-UDTypography -Text "Hello"
} -NavigationLayout permanent

$Pages += New-UDPage -Name 'Test2' -Content {
    New-UDTypography -Text "Hello"
} -NavigationLayout permanent


New-UDApp -Title "Hello, World!" -Pages $Pages

The temporary layout creates a navigation drawer that can be opened using a hamburger menu found in the top left corner. This is the default setting.

$Pages = @()
$Pages += New-UDPage -Name 'Test' -Content {
 New-UDTypography -Text "Hello"
} -NavigationLayout temporary

$Pages += New-UDPage -Name 'Test2' -Content {
    New-UDTypography -Text "Hello"
} -NavigationLayout temporary


New-UDApp -Title "Hello, World!" -Pages $Pages

You can use New-UDAppBar with a blank page to create horizontal navigation.

New-UDApp -Title 'PowerShell Universal' -Pages @(
    New-UDPage -Name 'Page' -Content {
        New-UDAppBar -Children {
            New-UDTypography -Text "Title" -Variant h4 -Style @{
                marginRight = "50px"
            }
            New-UDMenu -Variant text -Text "Settings" -Children {
                New-UDMenuItem -Text 'Item 1' -OnClick { Invoke-UDRedirect "/item1" }
                New-UDMenuItem -Text 'Item 2' -OnClick { Invoke-UDRedirect "/item1" }
                New-UDMenuItem -Text 'Item 3' -OnClick { Invoke-UDRedirect "/item1" }
            }
            New-UDMenu -Variant text -Text "Options" -Children {
                New-UDMenuItem -Text 'Item 1' -OnClick { Invoke-UDRedirect "/item1" }
                New-UDMenuItem -Text 'Item 2' -OnClick { Invoke-UDRedirect "/item1" }
                New-UDMenuItem -Text 'Item 3' -OnClick { Invoke-UDRedirect "/item1" }
            }
            New-UDMenu -Variant text -Text "Tools" -Children {
                New-UDMenuItem -Text 'Item 1' -OnClick { Invoke-UDRedirect "/item1" }
                New-UDMenuItem -Text 'Item 2' -OnClick { Invoke-UDRedirect "/item1" }
                New-UDMenuItem -Text 'Item 3' -OnClick { Invoke-UDRedirect "/item1" }
            }
        } -DisableThemeToggle
    } -Blank
)

Logo

You can display a logo in the navigation bar by using the -Logo parameter.

First, setup a published folder to host your logo.

Now, when creating your page, you can specify the path to the logo.

New-UDPage -Name 'Home' -Logo '/assets/favicon.png' -Content {
}

The logo will display in the top left corner.

To customize the style of your logo, you can use a cascading style sheet and target the ud-logo element ID.

Header Content

You can define custom content to include in the header by using the -HeaderContent parameter.

$Page = New-UDPage -Name 'Home' -Content {

} -HeaderContent {
    New-UDButton -Icon (New-UDIcon -Icon Users) -Text 'User'
}

New-UDApp -Title "Dashboard" -Pages $Page

Dynamic Page Title

Page titles are static by default, but you can override this behavior by using -LoadTitle. It will be called when the page is loaded. This is useful when defining pages in multilingual dashboards.

New-UDPage -Name "Home" -LoadTitle { "Current Time" + (Get-Date) } -Content { }

Static Pages

Static pages allow for better performance by not executing PowerShell to load the content of the page. This can be useful when displaying data that does not require dynamic PowerShell execution. The page content is constructed when the dashboard is started.

New-UDPage -Name 'Static Page' -Content {
    New-UDTypography (Get-Date)
} -Static

Static pages do not have access to user specific data. This includes variables such as:

$Headers
$User
$Roles

You can still include dynamic regions within pages. These dynamic regions will have access to user data. Reloading the below example will update the date and time listed in the page.

New-UDPage -Name 'Static Page' -Content {
   New-UDDynamic -Content {
       New-UDTypography (Get-Date)
   }
} -Static

API

New-UDPage

Dynamic Regions

Dynamic regions allow you control the reload of data within the region.

New-UDDynamic allows you to define a dynamic region. Pages themselves are dynamic in nature. This means that every time a page is loaded, it runs the PowerShell for that page. Sometimes, you may want to reload a section of a page rather than the whole page itself. This is when you will want to use dynamic regions.

Basic Dynamic Region

This dynamic region reloads when the button is clicked.

New-UDApp -Title "Hello, World!" -Content {
    New-UDDynamic -Id 'date' -Content {
        New-UDTypography -Text "$(Get-Date)"
    }

    New-UDButton -Text 'Reload Date' -OnClick { Sync-UDElement -Id 'date' }
}

Arguments List

An array of arguments may be passed to the dynamic region.

Note that the arguments are static and do not change when Sync-UDElement is invoked.

New-UDDynamic -Id 'dynamic_01' -Content {
    New-UDTypography -Text "This is an $($ArgumentList[0]) an $($ArgumentList[1]) in a UDDynamic"
} -ArgumentList @('example of', 'arguments list')

Auto Refresh

Dynamic regions enable the ability to auto refresh components after a certain amount of time. The entire region's script block will be run when autorefreshing.

If you have multiple related components that use the same data, consider putting them in the same dynamic region to improve performance.

    New-UDDynamic -Id 'date' -Content {
        New-UDTypography -Text "$(Get-Date)" -Variant h3
        New-UDTypography -Text "$(Get-Random)" -Variant h3
    } -AutoRefresh -AutoRefreshInterval 1

Loading Component

Sometimes refreshing a dynamic component may take some time. For example, if you are querying another service's REST API or a data. Dynamic regions support configuration of the component that shows when the region is reloading. By default, nothing is shown. This can be any app component.

    New-UDDynamic -Content {
        Start-Sleep -Seconds 3
        New-UDTypography -Text "Done!"
    } -LoadingComponent {
        New-UDProgress -Circular
    }

API

New-UDDynamic

Element

Information about UDElements.

The New-UDElement cmdlet allows you to create custom React elements within your app. Similar to New-UDHtml, you can define HTML elements using New-UDElement. Unlike, New-UDHtml, you can update elements, set auto refresh and take advantage of the React component system.

Create an Element

You need to specify the -Tag and -Content when creating an element. The below example creates a div tag.

New-UDElement -Tag 'div' -Content { 'Hello' }

You can nest components within each other to create HTML structures. For example, you could create an unordered list with the following example.

New-UDElement -Tag 'ul' -Content {
    New-UDElement -Tag 'li' -Content { 'First' }
    New-UDElement -Tag 'li' -Content { 'Second' }
    New-UDElement -Tag 'li' -Content { 'Third' }
}

Setting Attributes

You can select attributes of an element (like HTML attributes) by using the -Attributes parameter. This parameter accepts a hashtable of attribute name and values. The below example creates red text.

New-UDElement -Tag 'div' -Content { 'Hello' } -Attributes @{
    style = @{
        color = 'red'
    }
}

You can wrap any component with New-UDElement and add an event handler.

New-UDElement -Tag div -Content {
    New-UDIcon -Icon "user"
} -Attributes @{
    onClick = {
        Show-UDToast "Nice!"
    }
}

Auto Refreshing Elements

You can define the -AutoRefresh, -RefreshInterval and -Endpoint parameters to create an element the refreshes on a certain interval. The below example creates an element that refreshes every second and displays the current time.

New-UDElement -Tag 'div' -Endpoint {
    Get-Date
} -AutoRefresh -RefreshInterval 1

Setting Element Properties Dynamically

You can use the Set-UDElement cmdlet to set element properties and content dynamically. The following example sets the content of the element to the current time.

New-UDElement -Tag 'div' -Id 'myElement' -Content { }

New-UDButton -Text 'Click Me' -OnClick {
    Set-UDElement -Id 'myElement' -Content { Get-Date }
}

You can also set attributes by using the -Properties parameter of Set-UDElement. The following example sets the current time and changes the color to red.

    New-UDElement -Tag 'div' -Id 'myElement' -Content { }

    New-UDButton -Text 'Click Me' -OnClick {
        Set-UDElement -Id 'myElement' -Content { Get-Date } -Properties @{ Attributes = @{ style = @{ color = "red" } } }
    }

Adding Child Elements

You can add child elements using Add-UDElement. The following example adds child list items to an unordered list.

New-UDElement -Tag 'ul' -Content {

} -Id 'myList'

New-UDButton -Text 'Click Me' -OnClick {
    Add-UDElement -ParentId 'myList' -Content {
        New-UDElement -Tag 'li' -Content { Get-Date }
    }
}

Clearing Child Elements

You can clear the child elements of an element by using Clear-UDElement. The following example clears all the list items from an unordered list.

New-UDElement -Tag 'ul' -Content {
    New-UDElement -Tag 'li' -Content { 'First' }
    New-UDElement -Tag 'li' -Content { 'Second' }
    New-UDElement -Tag 'li' -Content { 'Third' }
}  -Id 'myList'

New-UDButton -Text 'Click Me' -OnClick {
    Clear-UDElement -Id 'myList'
}

Forcing an Element to Reload

You can force an element to reload using Sync-UDElement. The following example causes the div to reload with the current date.

New-UDElement -Tag 'div' -Endpoint {
    Get-Date
} -Id 'myDiv'

New-UDButton -Text 'Click Me' -OnClick {
    Sync-UDElement -Id 'myDiv'
}

Removing an Element

You can remove an element by using Remove-UDElement.

New-UDElement -Tag 'div' -Endpoint {
    Get-Date
} -Id 'myDiv'

New-UDButton -Text 'Click Me' -OnClick {
    Remove-UDElement -Id 'myDiv'
}

API

Error Boundary

Error boundary component for apps.

The New-UDErrorBoundary component is used for isolating portions of a dashboard to contain components that may throw an error. Many app components use the error boundary component internally.

If you'd like to isolate a portion of your app to prevent the entire page from failing to load, you can use the following syntax.

New-UDErrorBoundary -Content {
    throw "Oh no!"
}

If any error is thrown from the content, you will see an error such as thing.

API

New-UDErrorBoundary

HTML

Define static HTML using Univeral apps.

You can define static HTML using New-UDHtml. This cmdlet does not create React components but rather allows you to define static HTML. Any valid HTML string is supported.

The following creates an unordered list.

New-UDHtml -Markup "<ul><li>First</li><li>Second</li><li>Third</li></ul>"

API

New-UDHtml

Custom Components

Build custom components.

Components in PowerShell Universal apps are exposed as functions. You can combine built in components to produce your own custom components.

Designer Support

You can include your custom components as part of a module to allow for the designer to present them in the component picker. Parameters will automatically be displayed as properties in the component properties drawer.

Here's an example component the creates a textbox with a red border. It's required to include the Categoryattribute so that PowerShell Universal treats this function as an app component. You will need to define the app/component category and, optionally, a description and display name.

function New-UDRedbox {
    [Category("app/component")]
    [Description("A redbox component.")]
    [DisplayName("Redbox")]
    param(
        [Parameter()]
        [string]$Id
    )

    New-UDStyle -style "border: 2px solid red" -Content {
        New-UDTextbox -Id $Id
    }
}

The component will now be available within the designer. Once added, you can adjust the parameters are desired.

Example: People Picker

The below example creates a New-UDPeoplePicker component from existing app components. You can use the New-UDPeoplePicker component in your apps. This function can either be defined within your app directly or within a Module.

This example users a published folder of avatars.

function Get-User {
    1..100 | ForEach-Object {
        [PSCustomObject]@{
            UserName = "User$_"
            First = "Bill"
            Last = $_
            Avatar = (Get-ChildItem "$Repository\Avatars" | Get-Random).Name
        }
    }
}

function New-UDPeoplePicker {
   $Session:Users = [System.Collections.Generic.List[object]]::new()

    New-UDAutocomplete -OnLoadOptions {
        Get-User | Where-Object { $_.UserName -like "*$UserName*" } | Select-Object -First 5 -ExpandProperty 'UserName' | ConvertTo-Json 
    } -OnChange {
        $Session:Users.Add((Get-User | Where-Object { $_.UserName -eq $EventData })) | Out-Null
        Sync-UDElement -Id 'users'
    }

    New-UDDynamic -Id 'users' -Content {
        New-UDList -Children {
            $Session:Users | ForEach-Object {
                New-UDListItem -Label $_.UserName -SubTitle "$($_.First) $($_.Last)" -AvatarType 'Avatar' -SecondaryAction {
                    $UserName = $_.UserName
                    New-UDIconButton -Icon (New-UDIcon -Icon 'Trash') -OnClick {
                        $RemoveUser = $Session:Users | Where-Object { $_.UserName -eq $UserName }
                        $Session:Users.Remove($RemoveUser) 
                        Sync-UDElement -Id 'users'
                    }
                } -Source "/avatars/$($_.Avatar)"

            }    
        }
    }
}

New-UDApp -Title 'PowerShell Universal' -Content {
    New-UDPeoplePicker
}

Building Custom JavaScript Components

This document outlines how to build custom Universal app components.

Universal is extensible and you can build custom JavaScript components and frameworks. This document will cover how to build custom components that integrate with the Universal app platform.

This is an advanced topic and not required if you simply want to use Universal Apps.

Look at our blog post on how to get started with custom components for full end-to-end example.

Technology Overview

Below is a list of some of the technologies used when building Universal app components. You will not need to be an expert to produce a component but should be aware of what to search when you encounter a problem.

React

Universal App's client-side application is built using the React framework. React makes it easy to build components that update the DOM only when necessary and has a pretty robust ecosystem of users. It's one of the most popular JavaScript frameworks at the time of this writing.

Babel

Babel is a transcompiler for JavaScript. It works well with React and allows you to use modern constructs while compiling for backwards compatibility of browsers. Universal apps uses Babel for its core component frameworks.

Webpack

Webpack is an asset bundler. It's extremely customizable and is responsible for turning your JSX files into a bundle that can then be distributed with Universal App components.

Structure

There are some basic parts to a Universal App component. You will need to understand the structure in order to successfully build your own.

PowerShell Module

Universal App custom components are PowerShell modules. They export functions that can be used to create the component when run within an app. The PowerShell module is also responsible for registering the JavaScript assets with Universal App.

JavaScript Bundle

The JavaScript bundle is produced by the Webpack bundling process. It consists of one or more JS files that you will need to register with Universal.

Example Component Module Structure

The most basic structure for a Universal App component module will include a single JavaScript file, a PSM1 file to export a function and register the JavaScript and a PSD1 module manifest.

- UniversalApp.95
    - index.23adfdasf.js
    - UniversalApp.95.psd1
    - UniversalApp.95.psm1

Step-By-Step

This following section will take you step-by-step through the different aspects of building a Universal App component.

For a full example of a component, click here.

1. Installing Dependencies

You will need to install the following dependencies before creating your component.

2. Initialize the JavaScript Package

After installing Node, you will have access to the npm command. You will need to initialize the node package to start. This will create a package.json file in your directory.

npm init

Here is an example package.json that you can also use as a starting point.

3. Install JavaScript Packages

You will need several JavaScript packages to build your bundle. You will first want to install the dev dependencies. These are used to build your project.

npm install @babel/core --save-dev
npm install @babel/plugin-proposal-class-properties --save-dev
npm install @babel/plugin-syntax-dynamic-import --save-dev
npm install @babel/polyfill --save-dev
npm install @babel/preset-env --save-dev
npm install @babel/preset-react --save-dev
npm install babel-loader --save-dev
npm install webpack --save-dev
npm install webpack-cli --save-dev

Next, you'll want to install the universal-dashboard package along with any other packages you wish to use in your component. We are using React95 in this example. We will build a control based on that library.

npm install universal-dashboard --save
npm install react95 --save
npm install styled-components --save

4. Configure Babel

You will need to create a .babelrc file to configure Babel for React.

{
    "presets": ["@babel/preset-react"]
}

5. Configure Webpack

Webpack is extremely customizable and sometimes very hard to get right. Below is a basic webpack.config.js file you can use to configure Webpack. You can safely change the ud95 entry key name and library value to one that matches your library.

var path = require('path');

var BUILD_DIR = path.resolve(__dirname, 'dist');

module.exports = (env) => {
  const isDev = env == 'development' || env == 'isolated';

  return {
    entry: {
      'ud95' : __dirname + '/index.js'
    },
    output: {
      library: "UD95",
      libraryTarget: "var",
      path: BUILD_DIR,
      filename: isDev ? '[name].bundle.js' : '[name].[hash].bundle.js',
      sourceMapFilename: '[name].[hash].bundle.map',
      publicPath: "/"
    },
    module : {
      rules : [
        { test: /\.(js|jsx)$/, exclude: [/node_modules/, /public/], loader: 'babel-loader'}
      ]
    },
    externals: {
      UniversalDashboard: 'UniversalDashboard',
      'react': 'react',
      'react-dom': 'reactdom'
    },
    resolve: {
      extensions: ['.json', '.js', '.jsx']
    }
  };
}

6. Component.jsx

Now you can build your first component. You will need to export a single function component from your component.jsx file. We suggest the use of functional React components rather than class-based React components. We need to wrap the component in withComponentFeatures to ensure the component has access to the Universal App platform features.

import React from 'react';
import { withComponentFeatures } from 'universal-dashboard';
import { Button } from 'react95';

const UD95Button = props => {

    const p = {
        onClick: () => props.onClick()
    }

    return <Button {...p}>{props.text}</Button>
}

export default withComponentFeatures(UD95Button);

7. Index.js

Once your component is completed, you'll need to add it to an index.js file. The entry point for your library is the first place Webpack will look. It will discover all other components from import statements in your code. The index.js file is where you should register your components. You can use the registerComponent function to do so.

import { registerComponent } from 'universal-dashboard'
import UD95Button from './component';

registerComponent("ud95-button", UD95Button);

8. Bundle JavaScript

To bundle the JavaScript, run the following command to start webpack. This will output a file into the dist folder.

npm run build

9. PowerShell Script

Now you will need to create a PowerShell script that registers and creates your component.

First, register the JavaScript with Universal.

$JsFile = Get-ChildItem "$PSScriptRoot\ud95.*.js"
$AssetId = [UniversalDashboard.Services.AssetService]::Instance.RegisterAsset($JsFile.FullName)

Next, create a function that returns a hashtable that defines which component we are creating and which props to set.

The type property of your hashtable needs to match with the first parameter of registerComponent that you called in your JavaScript.

function New-UD95Button {
    param(
        [Parameter()]
        [string]$Id = [Guid]::NewGuid(),
        [Parameter()]
        [string]$Text,
        [Parameter()]
        [Endpoint]$OnClick
    )

    if ($OnClick)
    {
        $OnClick.Register($Id, $PSCmdlet)
    }

    @{
        type = "ud95-button"
        isPlugin = $true 
        assetId = $AssetId

        id = $Id 
        text = $Text 
        onClick = $OnClick
    }
}

10. InvokeBuild (optional)

We suggest the use of InvokeBuild to create a build script to run all the steps of packaging and staging your module. The below build script deletes the dist folder, runs an NPM install to install packages, runs an NPM build to bundle the JavaScript and then copies the PS module to the dist folder.

task Clean {
    Remove-Item "$PSScriptRoot\dist" -Recurse -Force
}

task NpmInstall {
    & {
        $ErrorActionPreference = 'SilentlyContinue'

        Push-Location $PSScriptRoot
        npm install
        Pop-Location
    }
}

task NpmBuild {
    & {
        $ErrorActionPreference = 'SilentlyContinue'

        Push-Location $PSScriptRoot
        npm run build
        Pop-Location
    }
}

task Stage {
    Copy-Item "$PSScriptRoot\UniversalDashboard.95.*" "$PSScriptRoot\dist"
}

task . Clean, NpmInstall, NpmBuild, Stage

Props

Props are values that are either passed from the PowerShell hashtable provided by the user or by the Universal App withComponentsFeature high-order function.

Standard

The properties that you set in your hashtable in PowerShell will automatically be sent in as props to React component.

For example, if you set the text property of the hashtable like this.

function New-UDText {
    param(
        [Parameter()]
        [string]$Text
    )

    @{
        type = "text"
        isPlugin = $true
        assetId = $AssetId 

        text = $Text
    }
}

Then you will have access to that prop in React.

import React from 'react';
import { withComponentFeatures } from 'universal-dashboard';

const UDText = props => {
    return <div>{props.text}</div>
}

export default withComponentFeatures(UDText);

Endpoints

Endpoints are special in the way they are registered and the way that they are passed as props to your component. You will need to call Register on the endpoint in PowerShell and pass in the Id and PSCmdlet variables.

function New-UD95Button {
    param(
        [Parameter()]
        [string]$Id = [Guid]::NewGuid(),
        [Parameter()]
        [string]$Text,
        [Parameter()]
        [Endpoint]$OnClick
    )

    if ($OnClick)
    {
        $OnClick.Register($Id, $PSCmdlet)
    }

    @{
        type = "ud95-button"
        isPlugin = $true 
        assetId = $AssetId

        id = $Id 
        text = $Text 
        onClick = $OnClick
    }
}

Endpoints are created from ScriptBlocks and are executed when that event happens.

New-UD95Button -Text 'Hello' -OnClick {
    Show-UDToast -Message 'Test' 
}

Universal will automatically wire up the endpoint to a function within JavaScript. This means that you can use the props to call that endpoint.

Notice the props.onClick function call. This will automatically call the PowerShell script block on the server.

import React from 'react';
import { withComponentFeatures } from 'universal-dashboard';
import { Button } from 'react95';

const UD95Button = props => {

    const p = {
        onClick: () => props.onClick()
    }

    return <Button {...p}>{props.text}</Button>
}

export default withComponentFeatures(UD95Button);

setState

The setState prop is used to set the state of the component. This ensures that the state is tracked and your component will work with Get-UDElement.

For example, with a text field, you'll want to call props.setState and pass in the new text value for the state.

const UDTextField = (props) => {
    const onChange = (e) => {
        props.setState({value: e.target.value})
    }

    return <TextField  {...props} onChange={onChange} />
}

export default withComponentFeatures(UDTextField);

children

The children prop is a standard React prop. If your component supports child items, such as a list or select box, you should use the standard props.children prop to ensure that the cmdlets Add-UDElement , Remove-UDElement and Clear-UDElement function correctly.

Data Display

Alert

Alert component for Universal Apps.

Alerts provide a simple way to communicate information to a user.

Simple Alerts

Alerts have four different severities and can include text or other content.

New-UDAlert -Severity 'error' -Text 'This is an error alert — check it out!' 
New-UDAlert -Severity 'warning' -Text 'This is an warning alert — check it out!'
New-UDAlert -Severity 'info' -Text 'This is an error info — check it out!' 
New-UDAlert -Severity 'success' -Text 'This is an success alert — check it out!'

Advanced Alerts

Alerts can contain any component and also a title.

New-UDAlert -Severity 'error' -Content { New-UDHtml 'This is an error alert — <strong>check it out!</strong>' } -Title "Error"
New-UDAlert -Severity 'warning' -Content { New-UDHtml 'This is an warning alert — <strong>check it out!</strong>' } -Title "Warning"
New-UDAlert -Severity 'info' -Content { New-UDHtml 'This is an error info — <strong>check it out!</strong>' } -Title "Info"
New-UDAlert -Severity 'success' -Content { New-UDHtml 'This is an success alert — <strong>check it out!</strong>' } -Title "Success"

API

New-UDAlert

Badge

Badges component for Universal Apps.

Basic Badge

Examples of badges containing text, using primary and secondary colors. The badge is applied to its children.

  New-UDBadge -BadgeContent { 4 } -Children {
      New-UDIcon -Icon Envelope -Size 2x
  } -Color primary

Color

New-UDBadge -BadgeContent { 4 } -Children {
    New-UDIcon -Icon Envelope -Size 2x
} -Color secondary
New-UDBadge -BadgeContent { 4 } -Children {
    New-UDIcon -Icon Envelope -Size 2x
} -Color success

API

New-UDBadge

Chip

Chip component for Universal Apps.

Chips are compact elements that represent an input, attribute, or action.

Chips allow users to enter information, make selections, filter content, or trigger actions.

While included here as a standalone component, the most common use will be in some form of input, so some of the behavior demonstrated here is not shown in context.

Basic Chips

Chips with Icons

OnClick

Shows a toast when the chip is clicked.

OnDelete

API

Data Grid

Data grid component for Universal Apps.

The UDDataGrid component is an advanced version of the table that is useful for displaying large amounts of data. It supports many of the same features as the table but also provides complex filtering, row virtualization, multi-column sort and more.

Simple Data Grid

Data grids load their data via the -LoadRows event handler. You will need to return a hashtable that contains the row data and the total number of rows.

Columns are defined using hashtables.

New-UDDataGrid -LoadRows {
    $Data = @(
        @{ Name = 'Adam'; Number = Get-Random}
        @{ Name = 'Tom'; Number = Get-Random}
        @{ Name = 'Sarah'; Number = Get-Random}
    )
    $Data | Out-UDDataGridData -Context $EventData -TotalRows $Rows.Length
} -Columns @(
    New-UDDataGridColumn -Field name
    New-UDDataGridColumn -Field number
) -AutoHeight $true

Columns

Columns are customizable using hashtables. You can find the supported properties below.

Property

Description

Type\Value

Align

How to align the data within the column.

Left, Center, Right

CellClassName

A CSS class to apply to cells in this column

string

ColSpan

The number of columns this column should span.

Integer

Description

A tooltip description of the column

string

DisableColumnMenu

Disable the column menu for this column

boolean

DisableExport

Disable exporting of the data in this column

boolean

Editable

Whether or not this column can be edited

boolean

Field

The field (property) to use when displaying the value in the column.

String

Filterable

Whether this column can be used in filters.

boolean

Flex

The flex property accepts a value between 0 and ∞. It works by dividing the remaining space in the grid among all flex columns in proportion to their flex value.

float

HeaderAlign

How to align header text.

left, center, right

HeaderName

The title to display in the header.

String

Hide

Whether to hide the column

boolean

Hideable

Whether a column can be hidden by the user.

boolean

HideSortIcon

Whether to hide the sort icon for the column

boolean

MaxWidth

The maximum width of the column

integer

MinWidth

The minimum width of the column

integer

Pinnable

Whether the column can be pinned.

boolean

Render

A script block to render components in the column

ScriptBlock

Resizable

Whether the column can be resized

boolean

Sortable

Whether the column can be sorted.

boolean

SortingOrder

A list of sorting options. Can be 'asc', 'desc', or $null

string[]

Type

The type of data within the column

string, number, date, dateTime, boolean, actions

Width

How wide the column should be in pixels.

Integer

Rendering Custom Columns

You can render custom components in columns by specifying render within the column hashtable. You can access the current row's data by using the $EventData or $Row variable

In this example, the number is shown in the name column with a New-UDTypography component.

New-UDDataGrid -LoadRows {  
    $Rows = 1..100 | % {
        @{ Name = 'Adam'; Number = Get-Random}
    }
    $Rows| Out-UDDataGridData -Context $EventData -TotalRows $Rows.Length
} -Columns @(
    New-UDDataGridColumn -Field name -Render {
         New-UDTypography $EventData.number 
    }
    New-UDDataGridColumn -Field number
) -AutoHeight $true

Flexible Width Columns

Column fluidity or responsiveness can be achieved by setting the flex property of a column.

The flex property accepts a value between 0 and ∞. It works by dividing the remaining space in the grid among all flex columns in proportion to their flex value.

For example, consider a grid with a total width of 500px that has three columns: the first with width: 200; the second with flex: 1; and the third with flex: 0.5. The first column will be 200px wide, leaving 300px remaining. The column with flex: 1 is twice the size of flex: 0.5, which means that final sizes will be: 200px, 200px, 100px.

To set a minimum and maximum width for a flex column set the minWidth and the maxWidth property on the column.

New-UDDataGrid -LoadRows {  
    $Rows = 1..100 | % {
        @{ Name = 'Adam'; Number = "This column is a very long string. This column is a very long string. This column is a very long string. This column is a very long string. This column is a very long string. This column is a very long string."}
    }        
    $Rows| Out-UDDataGridData -Context $EventData -TotalRows $Rows.Length
} -Columns @(
    New-UDDataGridColumn -Field name -Render {
         New-UDTypography $EventData.number 
    }
    New-UDDataGridColumn -Field number -Flex 1.0
) -AutoHeight $true

LoadRows

The -LoadRows parameter is used to return data for the data grid. Table state will be provided to the event handler as $EventData. You will find the following properties within the $EventData object.

Property

Description

Type

Filter

A filter object that you can use to construct filters against your data.

Hashtable

Page

The current page. Starts at 0.

Integer

PageSize

The number of records in a page.

Integer

Sort

The sort options for the table

Hashtable

Paging

To implement paging, you can access the page and pageSize properties of the $EventData variable. Out-UDDataGridData automatically implements paging.

New-UDDataGrid -LoadRows {  
    $Rows = 1..100 | % {
        @{ Name = 'Adam'; Number = Get-Random}
    } 
    $Rows| Out-UDDataGridData -Context $EventData -TotalRows $Rows.Length
} -Columns @(
    New-UDDataGridColumn -Field name
    New-UDDataGridColumn -Field number
) -AutoHeight $true -Pagination

Filtering

The filter hashtable is included in the $EventData for the -LoadRows event handler when a filter is defined. The hashtable has a structure as follows.

@{
    items = @(
        @{ 
            columnField = "Name"
            overatorValue = "contains"
            value = "test"
        }
    )
    linkOperator = "and"
}

Items

The items property contains an array of columns, operators and values. You can use these to filter your data.

Property

Description

Type

ColumnField

The name of the field to filter

String

OperatorValue

The type of operator to use when filtering the data.

String

Value

The value used to filter

Object

LinkOperator

The link operator field is used to specify the link between the filters. This can be and or or.

Sorting

The $EventData object will contain a Sort property when the user sorts the data grid. It contains properties for each column that is sorted. The properties will start as 0 and increment as more columns are sorted.

For example, you can access the first sorted column as follows.

$EventData.Sort.'0'.field

You will also receive the sort direction for each column.

Property

Description

Type

Field

The field to sort.

String

Sort

The direction to sort the field.

asc, desc

Detailed Content

You can use the -LoadDetailedContent event handler to display additional information about the row you are expanding. Information about the current row is available in $EventData.row.

New-UDDataGrid -LoadRows {
    $Data = @(
        @{ Name = 'Adam'; Number = Get-Random }
        @{ Name = 'Tom'; Number = Get-Random }
        @{ Name = 'Sarah'; Number = Get-Random }
    )
    $Data| Out-UDDataGridData -Context $EventData -TotalRows $Data.Length
} -Columns @(
    New-UDDataGridColumn -Field name
    New-UDDataGridColumn -Field number
) -AutoHeight $true -LoadDetailContent {
    Show-UDToast $Body
    New-UDAlert -Text $EventData.row.Name
}

Editing

Tables provide editor support by specifying the -OnEdit event handler. The new row data will be provided as $EventData. You can chose to return updated row information (for example, adjusting something the user has entered) and return it from the event handler. If you do not return anything, the row will reflect what the user entered.

The $EventData has the following format.

@{
    newRow = @{}
    oldRow = @{}
}

Ensure that you provide the editable property to each column you wish for the user to edit.

New-UDDataGrid -LoadRows {
    $Data = @(
        @{ Name = 'Adam'; number = Get-Random }
        @{ Name = 'Tom'; number = Get-Random }
        @{ Name = 'Sarah'; number = Get-Random }
    )
    $Data| Out-UDDataGridData -Context $EventData -TotalRows $Data.Length
} -Columns @(
    New-UDDataGridColumn -Field name -Editable
    New-UDDataGridColumn -Field number -Editable
) -AutoHeight $true -OnEdit {
    Show-UDToast "Editing $Body" 
}

Custom Export

To override the default export functionality, use the -OnExport event handler. $EventData will be an array of rows with their values. You should use Out-UDDataGridExport to return the data from -OnExport.

$Data = @(
    @{ name = 'Adam'; Number = Get-Random}
    @{ name = 'Tom'; Number = Get-Random}
    @{ name = 'Sarah'; Number = Get-Random}
)

New-UDDataGrid -LoadRows {
    @{
        rows = $Data 
        rowCount = $Data.Length
    }
} -Columns @(
    New-UDDataGridColumn -Field name
    New-UDDataGridColumn -Field number
) -OnExport {
    $ExportContent = $Data | ConvertTo-Csv -NoTypeInformation | Out-String
    Out-UDDataGridExport -Data $ExportContent -FileName 'export.csv' 
}

Example: Static Data

In this example, we generate an array of 10,000 records. We will create a new function, Out-UDDataGridData to manage the paging, sorting and filtering. This function is already included in the Universal module.

function Out-UDDataGridData {
    param(
        [Parameter(Mandatory)]
        $Context,
        [Parameter(Mandatory, ValueFromPipeline)]
        [object]$Data,
        [Parameter()]
        [int]$TotalRows = -1
    )
    Begin {
        $Items = [System.Collections.ArrayList]::new()
    }
    Process {
        $Items.Add($Data) | Out-Null
    }

    End {
        $simpleFilter = @()
        if($null -ne $Context.Filter.Items -and $Context.Filter.Items.Count -gt 0) {
            $linkOperator = $Context.Filter.linkOperator
            $count = 1
            $filterTextArray = @()
            foreach($filter in $Context.Filter.Items) {
                $property = $Filter.columnField
                $val = $filter.Value
                switch ($filter.operatorValue) {
                    "contains" { $filterTextArray += "obj.$property -like ""*$val*""" }
                    "equals" { $filterTextArray += "obj.$property -eq ""*$val*""" }
                    "startsWith" { $filterTextArray += "obj.$property -like ""$val*""" }
                    "endsWith" { $filterTextArray += "obj.$property -like ""*$val""" }
                    "isAnyOf" { $filterTextArray += "obj.$property -in ""$val""" }
                    "notequals" {$filterTextArray += "obj.$property -ne ""$val""" }
                    "notcontains" { $filterTextArray += "obj.$property -notlike ""*$val*""" }
                    "isEmpty" { $filterTextArray += "obj.$property -eq null" }
                    "isNotEmpty" { $filterTextArray += "obj.$property -ne null" }
                }
            }
            if ($linkOperator -eq 'and') {
                [string]$filterTextLine = $filterTextArray -join " -and "
            } else {
                [string]$filterTextLine = $filterTextArray -join " -or "
            }

            $filterTextLine = $filterTextLine.Replace('obj','$_')
            $filterTextLine = $filterTextLine.Replace('null','$null')
            $filterScriptBlock = [Scriptblock]::Create($filterTextLine)
            $Items = $Items | Where-Object -FilterScript $filterScriptBlock
        }

        if ($null -ne $Items) {
            $TotalRows = $Items.Count
        } else {
            $TotalRows = 0
        }

        $Sort = $Context.Sort[0]
        $Items = $Items | Sort-Object -Property $Sort.field -Descending:$($Sort.Sort -eq 'desc')
        $Items = $Items | Select-Object -Skip ($Context.Page * $Context.pageSize) -First $Context.PageSize

        @{
            rows     = [Array]$Items
            rowCount = $TotalRows
        }
    }   
}

New-UDDashboard -Title 'PowerShell Universal' -Content {
     $Data =  1..10000 | % {
        @{ Name = 'Adam'; Number = Get-Random }
    } 
    New-UDDataGrid -LoadRows {  
      $Data | Out-UDDataGridData -Context $EventData
    } -Columns @(
        New-UDDataGridColumn -Field name
        New-UDDataGridColumn -Field number -Render {
            New-UDButton -Icon (New-UDIcon -Icon User) -OnClick { Show-UDToast $EventData.Name } } 
        }
    ) -AutoHeight $true -Pagination
}

Example: SQL Data

In this example, we'll query the PowerShell Universal database with dbatools.

function Out-UDSQLDataGrid {
    param(
        $Context,
        [Parameter(Mandatory)]
        [string]$Table,
        [Parameter(Mandatory)]
        [string]$SqlInstance,
        [Parameter(Mandatory)]
        [string]$Database,
        [Parameter(Mandatory)]
        [pscredential]$SqlCredential,
        [Int32]$RowsPerPage
    )

    End {
        $simpleFilter = @()

        if ($null -ne $Context.Filter.Items -and $Context.Filter.Items.Count -gt 0) {
            $logicOperator = $Context.Filter.logicOperator #The link operator is 'AND' or 'OR'. It will always be one or the other for all properties

            foreach ($item in $Context.Filter.Items) {         
                $simpleFilter += [PSCustomObject]@{
                    Property = $item.Field
                    Value    = $item.Value
                    Operator = $item.Operator
                }
            }
        }

        if ($null -ne $simpleFilter -and $simpleFilter.Count -gt 0) {
            $count = 1
            foreach ($filter in $simpleFilter) {
                if ($count -gt 1) {               
                    $SqlFilter += " $($logicOperator) "
                }
                else {
                    $SqlFilter += " WHERE "
                }

                switch ($filter.Operator) {
                    "contains" { $SqlFilter += " $($filter.Property) LIKE '%$($filter.Value)%' " }
                    "equals" { $SqlFilter += " $($filter.Property) = '$($filter.Value)' " }
                    "startsWith" { $SqlFilter += " $($filter.Property) LIKE '$($filter.Value)%' " }
                    "endsWith" { $SqlFilter += " $($filter.Property) LIKE '%$($filter.Value)' " }
                    "isAnyOf" {
                        $count = 1
                        foreach ($val in $filter.Value) {
                            if ($count -gt 1) {
                                $list += ", '$val'"
                            }
                            else {
                                $list += "'$val'"
                            }  
                            $count += 1
                        }
                        $SqlFilter += " $($filter.Property) IN ($($list)) "
                    }
                    "isempty" { $SqlFilter += " TRIM ($($filter.Property)) IS NULL " }
                    "isnotempty" { $SqlFilter += " TRIM ($($filter.Property)) IS NOT NULL " }
                    "notequals" { $SqlFilter += " $($filter.Property) != '$($filter.Value)' " }
                    "notcontains" { $SqlFilter += " $($filter.Property) NOT LIKE '%$($filter.Value)%' " }
                }
                $count += 1
            }
        }
        else {
            $SqlFilter = $null
        }

        if ($null -eq $SqlFilter) {
            $totalCount = (Invoke-DbaQuery -SqlInstance $SqlInstance -Database $Database -SqlCredential $SqlCredential -Query "SELECT COUNT(*) As Count FROM $Table").Count
        }
        else {
            $totalCount = (Invoke-DbaQuery -SqlInstance $SqlInstance -Database $Database -SqlCredential $SqlCredential -Query "SELECT COUNT(*) As Count FROM $Table $SqlFilter").Count
            $sort = $Context.Sort.'0'
        }

        if ($sort) {
            $sqlSort = "ORDER BY $($sort.field) $($sort.Sort) "
        }
        else {
            $sqlSort = "ORDER BY (SELECT NULL)"
        }

        if ($null -ne $SqlFilter) {
            $sqlPage = "OFFSET $($Context.Page * $Context.PageSize) ROWS FETCH NEXT $($Context.PageSize) ROWS ONLY;"
            $Query = "SELECT * FROM $Table $sqlFilter $sqlSort $sqlPage"
        }
        else {
            $sqlPage = "OFFSET $($RowsPerPage) ROWS FETCH NEXT $($RowsPerPage) ROWS ONLY;"
            $Query = "SELECT * FROM $Table $sqlSort $sqlPage"
        }

        $Rows = Invoke-DbaQuery -SqlInstance $SqlInstance -Database $Database -SqlCredential $SqlCredential -Query $Query -As PSObject

        @{
            rows     = [Array]$Rows
            rowCount = $TotalCount
        }
    }   
}

New-UDDashboard -Title 'PowerShell Universal' -Content {
    New-UDDataGrid -LoadRows {  
      Out-UDSqlDataGrid -Context $EventData -SqlInstance "(localdb)\MSSQLLocalDb" -Database "PSU" -Table "Job"
    } -Columns @(
        New-UDDataGridColumn -Field id
        New-UDDataGridColumn -Field startTime
        New-UDDataGridColumn -Field status -Render {
          if ($EventData.Status -eq 2) {
                New-UDAlert -Severity 'Success' -Text 'Success'
            }

            if ($EventData.Status -eq 3) {
                New-UDAlert -Severity 'Error' -Text 'Failed'
            }
        }
    ) -AutoHeight $true -Pagination
}

Date and Time

Date and time component for Universal Apps.

The New-UDDateTime component is used for formatting dates and times within the client's browser. By using the client's browser, you can format the time based on the local time zone and locale settings for the user.

The output of New-UDDateTime cannot be used with components like New-UDHtml, New-UDMarkdown or Show-UDToast. The object returned by New-UDDateTime needs to run JavaScript within the browser and is not an actual DateTime object.

The date and time component uses DayJS. For a full list of custom formatting options, visit the .

Basic Formatting

By default, the date and time will be formatted using the LLL localized formatting template.

Resulting output: August 16, 2018 8:02 PM

Custom Formatting

You can specify custom formatting strings using the .

Resulting output: 25/01/2019

Locale

You can specify the locale to display the date and time in.

Resulting output: 13 de septiembre de 2022 7:30

API

Icon

Icon component for Universal Apps

icons to include in your app. Icon names are slightly different than those shown on the FontAwesome website. For example, if you want to use the network-wired icon, you would use the following string.

Finding an Icon

We include FontAwesome v6 with PowerShell Universal. You can use Find-UDIcon to search through the list of included icons.

The UniversalDashboard.FontAwesomeIcons enum should not be used and is only included for backwards compatibility. Many of the icons are no longer a part of FontAwesome 6.

Icon

Create icons by specifying their names. You can use the icon reference below to find icons.

Size

Set the size of the icon. Valid values are: xs, sm, lg, 2x, 3x, 4x, 5x, 6x, 7x, 8x, 9x, 10x

Rotation

Rotate icons. The value represents the degrees of rotation.

Border

Add a border to your icon.

Style

Apply CSS styles to your icon.

Visually Search for Icons

Complete Icon List

API

List

List component for Universal Apps.

Lists are continuous, vertical indexes of text or images.

Lists are a continuous group of text or images. They are composed of items containing primary and supplemental actions, which are represented by icons and text.

List

OnClick Event Handler

You can define an action to take when an item is clicked by using the -OnClick parameter of New-UDListItem.

API

Markdown

Markdown display for Universal Apps.

New-UDMarkdown accepts a markdown string and renders it as HTML elements within a dashboard.

API

New-UDMarkdown

Timeline

Time line control for PowerShell Universal Apps

The timeline control can be used to display a sequence of events over time.

Basic Timeline

Create a basic timeline with information on both sides of the timeline.

New-UDTimeline -Children {
    New-UDTimelineItem -Content {
        'Breakfast'
    } -OppositeContent {
        '7:45 AM'
    } 
    New-UDTimelineItem -Content {
        'Welcome Message'
    } -OppositeContent {
        '9:00 AM'
    }
    New-UDTimelineItem -Content {
        'State of the Shell'
    } -OppositeContent {
        '9:30 AM'
    }
    New-UDTimelineItem -Content {
        'General Session'
    } -OppositeContent {
        '11:00 AM'
    }
}

Alternating Timeline

New-UDTimeline -Children {
    New-UDTimelineItem -Content {
        'Breakfast'
    } -OppositeContent {
        '7:45 AM'
    } 
    New-UDTimelineItem -Content {
        'Welcome Message'
    } -OppositeContent {
        '9:00 AM'
    }
    New-UDTimelineItem -Content {
        'State of the Shell'
    } -OppositeContent {
        '9:30 AM'
    }
    New-UDTimelineItem -Content {
        'General Session'
    } -OppositeContent {
        '11:00 AM'
    }
} -Position alternate

Colors

New-UDDashboard -Title 'PowerShell Universal' -Content {
        New-UDTimeline -Children {
            New-UDTimelineItem -Content {
                'Breakfast'
            } -OppositeContent {
                '7:45 AM'
            }  -Color 'error'
            New-UDTimelineItem -Content {
                'Welcome Message'
            } -OppositeContent {
                '9:00 AM'
            } -Color 'info'
            New-UDTimelineItem -Content {
                'State of the Shell'
            } -OppositeContent {
                '9:30 AM'
            } -Color 'success'
            New-UDTimelineItem -Content {
                'General Session'
            } -OppositeContent {
                '11:00 AM'
            } -Color 'grey'
        } -Position alternate
}

Icons

New-UDTimeline -Children {
    New-UDTimelineItem -Content {
        'Breakfast'
    } -OppositeContent {
        '7:45 AM'
    }  -Icon (New-UDIcon -Icon Microsoft)
    New-UDTimelineItem -Content {
        'Welcome Message'
    } -OppositeContent {
        '9:00 AM'
    } -Icon (New-UDIcon -Icon Apple)
    New-UDTimelineItem -Content {
        'State of the Shell'
    } -OppositeContent {
        '9:30 AM'
    } -Icon (New-UDIcon -Icon NetworkWired)
    New-UDTimelineItem -Content {
        'General Session'
    } -OppositeContent {
        '11:00 AM'
    } -Icon (New-UDIcon -Icon User)
} -Position alternate

API

New-UDTimeline
New-UDTimelineItem

Tooltip

Tooltip component for PowerShell Universal Apps.

Tooltips display informative text when users hover over an element.

New-UDTooltip -Content {
    New-UDIcon -Icon 'User'
} -TooltipContent {
    "User"
}

Placement

Place the tooltip on top, bottom, left or right.

New-UDTooltip -Content {
    New-UDIcon -Icon 'User'
} -TooltipContent {
    "User"
} -Place 'bottom'

Custom Content

Tooltip content can contain any UD element.

New-UDTooltip -Content {
    New-UDIcon -Icon 'User'
} -TooltipContent {
    New-UDPaper -Children {
        "User"
    }
}

Tooltips can be over various types including: "dark", "success", "warning", "error", "info", "light"

New-UDTooltip -Content {
    New-UDIcon -Icon 'User'
} -TooltipContent {
    "User"
} -Type 'success'

Tree View

Tree view component for Universal Apps.

New-UDTreeView allows you to create a tree of items and, optionally, dynamically expand the list when clicked.

Basic Tree View

Create a basic tree view by using the New-UDTreeNode cmdlet.

New-UDTreeView -Node {
    New-UDTreeNode -Name 'Level 1' -Children {
        New-UDTreeNode -Name 'Level 2 - Item 1' 
        New-UDTreeNode -Name 'Level 2 - Item 2'
        New-UDTreeNode -Name 'Level 2 - Item 3' -Children {
            New-UDTreeNode -Name 'Level 3'
        }
    }
}

Dynamic Tree View

Dynamic tree views allow you to run PowerShell whenever a node is clicked. You can then return a list of nodes that should be rendered underneath the clicked node. You can also take other actions such as opening a modal or showing a toast.

New-UDDashboard -Title 'File System' -Content {
    Get-PSDrive -PSProvider 'FileSystem' | ForEach-Object {
        New-UDTreeView -Node { New-UDTreeNode -Name $_.Name -Id "$($_.Name):\" } -OnNodeClicked {
            Get-ChildItem $EventData.Id | ForEach-Object {
                New-UDTreeNode -Name $_.Name -Id $_.FullName -Leaf:$(-not $_.PSIsContainer)
            }
        }
    }
}

API

Typography

Typography component for Universal Apps

Use typography to present your design and content as clearly and efficiently as possible.

Too many type sizes and styles at once can spoil any layout. A typographic scale has a limited set of type sizes that work well together along with the layout grid.

All Typography Types

@("h1", "h2", "h3", "h4", "h5", "h6", "subtitle1", "subtitle2", "body1", "body2", 
"caption", "button", "overline", "srOnly", "inherit", 
"display4", "display3", "display2", "display1", "headline", "title", "subheading") | ForEach-Object {
    New-UDTypography -Variant $_ -Text $_ -GutterBottom
    New-UDElement -Tag 'p' -Content {}
}

Colored Text

You can use the -Style parameter to define colors for your text.

New-UDTypography -Text 'My Text' -Style @{ color = 'blue' }

Theme-based Styling

You can use theme-based styling by using the -Sx parameter of New-UDTypography. For example, to apply the secondary text color, you can use the following syntax.

New-UDTypography -Text 'Secondar' -Sx @{
    color = 'text.secondary'
}

API

New-UDTypography

Data Visualization

Charts

Charting components for Universal Apps.

Universal Apps provides several built-in charting solutions to help visualize your data retrieved from PowerShell.

ChartJS

Universal Apps integrates with ChartJS.

Creating a Chart

To create a chart, use New-UDChartJS and New-UDChartJSData. The below chart shows the top ten CPU using processes.

 $Data = Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10 
 New-UDChartJS -Type 'bar' -Data $Data -DataProperty CPU -LabelProperty ProcessName

Types

Bar

 $Data = Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10 
 New-UDChartJS -Type 'bar' -Data $Data -DataProperty CPU -LabelProperty ProcessName

Stacked Bar

    $GraphPrep = @(
        @{ RAM = "Server1"; AvailableRam = 128; UsedRAM = 10 }
        @{ RAM = "Server2"; AvailableRam = 64; UsedRAM = 63 }
        @{ RAM = "Server3"; AvailableRam = 48; UsedRAM = 40 }
        @{ RAM = "Server4"; AvailableRam = 64;; UsedRAM = 26 }
        @{ RAM = "Server5"; AvailableRam = 128; UsedRAM = 120 }
    )

    $AvailableRamDataSet = New-UDChartJSDataset -DataProperty AvailableRAM -Label 'Available' -BackgroundColor blue
    $UsedRamDataset = New-UDChartJSDataset -DataProperty UsedRAM -Label 'Used' -BackgroundColor red
    $Options = @{
        Type          = 'bar'
        Data          = $GraphPrep
        Dataset       = @($AvailableRamDataSet, $UsedRamDataset)
        LabelProperty = "RAM"
        Options = @{
            scales = @{
                xAxes = 
                @{
                    stacked = $true
                }            
            yAxes = 
                @{
                    stacked = $true
                }            
            }
        }
    } 

    New-UDChartJS @Options

Horizontal Bar

    $Data = Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10 
    New-UDChartJS -Type 'bar' -Data $Data -DataProperty CPU -LabelProperty ProcessName -Options @{
        indexAxis = "y"
        plugins = @{
            legend = @{
                position = "right"
            }
        }
    }p

Bubble

A bubble chart consists of x and y coordinates and an r value for the radius of the circles.

$Data = @(
    @{ x = 1; y = 10; r = 15 }
    @{ x = 12; y = 25; r = 35 }
    @{ x = 8; y = 10; r = 95 }
    @{ x = 6; y = 95; r = 25 }
)
New-UDChartJS -Type 'bubble' -Data $Data

Line

 $Data = Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10 
 New-UDChartJS -Type 'line' -Data $Data -DataProperty CPU -LabelProperty ProcessName

Doughnut

 $Data = Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10 
 New-UDChartJS -Type 'doughnut' -Data $Data -DataProperty CPU -LabelProperty ProcessName

Pie

 $Data = Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10 
 New-UDChartJS -Type 'pie' -Data $Data -DataProperty CPU -LabelProperty ProcessName

Radar

 $Data = Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10 
 New-UDChartJS -Type 'radar' -Data $Data -DataProperty CPU -LabelProperty ProcessName

Colors

Colors can be defined using the various color parameters of New-UDChartJS.

 $Data = Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10 

 $Options = @{
   Type = 'bar'
   Data = $Data
   BackgroundColor = 'Red'
   BorderColor = '#c61d4a'
   HoverBackgroundColor = 'Blue'
   HoverBorderColor = '#451dc6'
   DataProperty = 'CPU'
   LabelProperty = 'ProcessName'
 }

 New-UDChartJS @Options

Data Sets

By default, you do not need to define data sets manually. A single data set is created automatically when you use the -DataProperty and -LabelProperty parameters. If you want to define multiple data sets for a single chart, you can use the -Dataset property in conjunction with New-UDChartJSDataset.

$Data = Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10 

 $CPUDataset = New-UDChartJSDataset -DataProperty CPU -Label CPU -BackgroundColor '#126f8c'
 $MemoryDataset = New-UDChartJSDataset -DataProperty HandleCount -Label 'Handle Count' -BackgroundColor '#8da322'

 $Options = @{
   Type = 'bar'
   Data = $Data
   Dataset = @($CPUDataset, $MemoryDataset)
   LabelProperty = "ProcessName"
 }

 New-UDChartJS @Options

Click Events

You can take action when a user clicks the chart. This example shows a toast with the contents of the $Body variable. The $Body variable contains a JSON string with information about the elements that were clicked.

 $Data = Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10 

  $Options = @{
   Type = 'bar'
   Data = $Data
   DataProperty = 'CPU'
   LabelProperty = "ProcessName"
   OnClick = { 
      Show-UDToast -Message $Body
   }
 }


 New-UDChartJS @Options

Auto refreshing charts

You can use New-UDDynamic to create charts that refresh on an interval.

New-UDDynamic -Content {
    $Data = 1..10 | % { 
        [PSCustomObject]@{ Name = $_; value = get-random }
    }
    New-UDChartJS -Type 'bar' -Data $Data -DataProperty Value -Id 'test' -LabelProperty Name -BackgroundColor Blue
} -AutoRefresh -AutoRefreshInterval 1

Monitors

Monitors are a special kind of chart that tracks data over time. Monitors are good for displaying data such as server performance stats that change frequently. You return a single value from a monitor and it is graphed automatically over time.

New-UDChartJSMonitor -LoadData {
    Get-Random -Max 100 | Out-UDChartJSMonitorData
} -Labels "Random" -ChartBackgroundColor "#297741" -RefreshInterval 1

Options

The New-UDChartJS cmdlet supports accepting advanced ChartJS options. You can use the -Options parameter to pass in a hashtable.

This example hides the legend.

 $Data = Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10 
 New-UDChartJS -Type 'bar' -Data $Data -DataProperty CPU -LabelProperty ProcessName -Options @{  
 legend = @{  
     display = $false  
 }  
}

Title

You can include a title with the title option.

$Data = Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10 
New-UDChartJS -Type 'bar' -Data $Data -DataProperty CPU -LabelProperty ProcessName -Options @{
    plugins = @{
        legend = @{
            title = @{
                display = $true
                text    = 'Bar Chart'
            }
        }
    }
}

Nivo Charts

Universal Dashboard integrates with Nivo Charts. Below you will find examples and documentation for using these charts.

Creating a Chart

All the Nivo charts can be created with New-UDNivoChart. You will specify a switch parameter for the different types of charts. Each chart type will take a well defined data format via the -Data parameter.

$Data = 1..10 | ForEach-Object { 
    $item = Get-Random -Max 1000 
    [PSCustomObject]@{
        Name = "Test$item"
        Value = $item
    }
}
New-UDNivoChart -Id 'autoRefreshingNivoBar' -Bar -Keys "value" -IndexBy 'name' -Data $Data -Height 500 -Width 1000

Patterns

Nivo provides the ability to specify patterns to display over data sets. You can configure these patterns with New-UDNivoPattern and New-UDNivoFill .

$Data = @(
    @{
        country = 'USA'
        burgers = (Get-Random -Minimum 10 -Maximum 100)
        fries = (Get-Random -Minimum 10 -Maximum 100)
        sandwich = (Get-Random -Minimum 10 -Maximum 100)
    }
    @{
        country = 'Germany'
        burgers = (Get-Random -Minimum 10 -Maximum 100)
        fries = (Get-Random -Minimum 10 -Maximum 100)
        sandwich = (Get-Random -Minimum 10 -Maximum 100)
    }
    @{
        country = 'Japan'
        burgers = (Get-Random -Minimum 10 -Maximum 100)
        fries = (Get-Random -Minimum 10 -Maximum 100)
        sandwich = (Get-Random -Minimum 10 -Maximum 100)
    }
)

$Pattern = New-UDNivoPattern -Dots -Id 'dots' -Background "inherit" -Color "#38bcb2" -Size 4 -Padding 1 -Stagger
$Fill = New-UDNivoFill -ElementId "fries" -PatternId 'dots'

New-UDNivoChart -Definitions $Pattern -Fill $Fill -Bar -Data $Data -Height 400 -Width 900 -Keys @('burgers', 'fries', 'sandwich')  -IndexBy 'country'

Responsive Widths

Nivo charts provide responsive widths so they will resize automatically when placed on a page or the browser is resized. A height is required when using responsive widths.

Auto Refreshing Charts

Like many components in Universal Dashboard v3, Nivo charts do not define auto-refresh properties themselves. Instead, you can take advantage of New-UDDynamic to refresh the chart on an interval.

New-UDDynamic -Content {
    $Data = 1..10 | ForEach-Object { 
        $item = Get-Random -Max 1000 
        [PSCustomObject]@{
            Name = "Test$item"
            Value = $item
        }
    }
    New-UDNivoChart -Id 'autoRefreshingNivoBar' -Bar -Keys "Value" -IndexBy 'name' -Data $Data -Height 500 -Width 1000
} -AutoRefresh

OnClick

Nivo charts support OnClick event handlers. You will be provided with information about the data set that was clicked as JSON.

$Data = @(
    @{
        country = 'USA'
        burgers = (Get-Random -Minimum 10 -Maximum 100)
        fries = (Get-Random -Minimum 10 -Maximum 100)
        sandwich = (Get-Random -Minimum 10 -Maximum 100)
    }
    @{
        country = 'Germany'
        burgers = (Get-Random -Minimum 10 -Maximum 100)
        fries = (Get-Random -Minimum 10 -Maximum 100)
        sandwich = (Get-Random -Minimum 10 -Maximum 100)
    }
    @{
        country = 'Japan'
        burgers = (Get-Random -Minimum 10 -Maximum 100)
        fries = (Get-Random -Minimum 10 -Maximum 100)
        sandwich = (Get-Random -Minimum 10 -Maximum 100)
    }
)
New-UDNivoChart -Bar -Data $Data -Height 400 -Width 900 -Keys @('burgers', 'fries', 'sandwich')  -IndexBy 'country' -OnClick {
    Show-UDToast -Message $EventData -Position topLeft
}

Types of Charts

Bar

New-Example -Title 'Bar' -Description '' -Example {
    $Data = 1..10 | ForEach-Object { 
        $item = Get-Random -Max 1000 
        [PSCustomObject]@{
            Name = "Test$item"
            Value = $item
        }
    }
    New-UDNivoChart -Bar -Keys "Value" -IndexBy 'name' -Data $Data -Height 500 -Width 1000
}

Bubble

$TreeData = @{
    Name     = "root"
    children = @(
        @{
            Name  = "first"
            children = @(
                @{
                    Name = "first-first"
                    Count = 7
                }
                @{
                    Name = "first-second"
                    Count = 8
                }
            )
        },
        @{
            Name  = "second"
            Count = 21
        }
    )
}

New-UDNivoChart -Bubble -Data $TreeData -Value "count" -Identity "name" -Height 500 -Width 800

Calendar

$Data = @()
for($i = 365; $i -gt 0; $i--) {
    $Data += @{
        day = (Get-Date).AddDays($i * -1).ToString("yyyy-MM-dd")
        value = Get-Random
    }
}

$From = (Get-Date).AddDays(-365)
$To = Get-Date

New-UDNivoChart -Calendar -Data $Data -From $From -To $To -Height 500 -Width 1000 -MarginTop 50 -MarginRight 130 -MarginBottom 50 -MarginLeft 60

Heatmap

$Data = @(
    @{
        state = "idaho"
        cats = 72307
        dogs = 23429
        moose = 23423
        bears = 784
    }
    @{
        state = "wisconsin"
        cats = 2343342
        dogs = 3453623
        moose = 1
        bears = 23423
    }
    @{
        state = "montana"
        cats = 9234
        dogs = 3973457
        moose = 23472
        bears = 347303
    }
    @{
        state = "colorado"
        cats = 345973789
        dogs = 0237234
        moose = 2302
        bears = 2349772
    }
)
New-UDNivoChart -Heatmap -Data $Data -IndexBy 'state' -keys @('cats', 'dogs', 'moose', 'bears')  -Height 500 -Width 1000 -MarginTop 50 -MarginRight 130 -MarginBottom 50 -MarginLeft 60

Line

[array]$Data = [PSCustomObject]@{
    id = "DataSet"
    data = (1..20 | ForEach-Object {
        $item = Get-Random -Max 500 
        [PSCustomObject]@{
            x = "Test$item"
            y = $item
        }
    })
}
New-UDNivoChart -Line -Data $Data -Height 500 -Width 1000 -LineWidth 1

Stream

$Data = 1..10 | ForEach-Object { 
    @{
        "Adam" = Get-Random 
        "Alon" = Get-Random 
        "Lee" = Get-Random 
        "Frank" = Get-Random 
        "Bill" = Get-Random 
    }
}

New-UDNivoChart -Stream -Data $Data -Height 500 -Width 1000 -Keys @("adam", "alon", "lee", "frank", "bill")

Treemap

$TreeData = @{
    Name     = "root"
    children = @(
        @{
            Name  = "first"
            children = @(
                @{
                    Name = "first-first"
                    Count = 7
                }
                @{
                    Name = "first-second"
                    Count = 8
                }
            )
        },
        @{
            Name  = "second"
            Count = 21
        }
    )
}

New-UDNivoChart -Treemap -Data $TreeData -Value "count" -Identity "name" -Height 500 -Width 800

Color Based on Data

You can use the following format to use colors based on your data.

$Data =
$([PSCustomObject]@{
        value = 30
        color = '#BF5290'
    }
    [PSCustomObject]@{
        value = 100
        color = '#52BE80'

    }
)

New-UDNivoChart -Pie -Data ($Data | Where-Object { $_.Value -ne 0 }) -InnerRadius 0.7 -CornerRadius 5 -PadAngle 1 -Colors @{datum = 'data.color' }` -MarginLeft "150" -MarginTop 1 -Height 370 -Responsive

Image

Image component for apps.

Image by URL

Display an image based on a URL. You can host URLs using Published Folders.

New-UDImage -Url "https://ironmansoftware.com/img/ps-logo.png"

Image by Path

Display an image based on a file local to the server.

New-UDImage -Path C:\users\adamr\Desktop\ps-logo.png

Image Size

Change the size of the image using the -Width and -Height parameters.

New-UDImage -Url "https://ironmansoftware.com/img/ps-logo.png" -Width 250 -Height 250

Attributes

Apply additional attributes to the image.

New-UDImage -Url "https://ironmansoftware.com/img/ps-logo.png" -Attributes @{
    alt = "Ironman Software Logo"
}

API

New-UDImage

Map

Map component for Universal Apps.

The UDMap component is a robust control that provides a huge set of features. You can select base layers, configure togglable layers, set markers, define vectors and interact with other Universal App components.

Basic Map

This basic map defines a simple base layer using the wmflabs.org tile server. You can use your own custom tile server by specifying a URL. The map is position over Hailey, Idaho.

New-UDMap -Endpoint {
    New-UDMapRasterLayer -TileServer 'https://tiles.wmflabs.org/bw-mapnik/{z}/{x}/{y}.png' 
} -Latitude 43.52107 -Longitude -114.31644 -Zoom 13 -Height '100vh'

Layer Control

You can enable the layer control by using the New-UDMapLayerControl cmdlet. This map defines several layers with components that you can toggle on and off. You can only have one base layer selected as a time. Map overlay layers can toggle on and off.

New-UDMap -Endpoint {
    New-UDMapLayerControl -Content {
        New-UDMapBaseLayer -Name 'Black and White' -Content {
            New-UDMapRasterLayer -TileServer 'https://tiles.wmflabs.org/bw-mapnik/{z}/{x}/{y}.png' 
        } -Checked
        New-UDMapBaseLayer -Name 'Color' -Content {
            New-UDMapRasterLayer -TileServer 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png' 
        }
        New-UDMapOverlay -Name 'Marker' -Content {
            New-UDMapMarker -Latitude 51.505 -Longitude -0.09 
        } -Checked
        New-UDMapOverlay -Name 'Marker 2' -Content {
            New-UDMapMarker -Latitude 51.555 -Longitude -0.00 
        } -Checked
    }
} -Latitude 51.505 -Longitude -0.09 -Zoom 13 -Height '100vh'

Markers

Markers are used to highlight particular locations.

New-UDMap -Endpoint {
    New-UDMapRasterLayer -TileServer 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png' 
    New-UDMapMarker -Latitude "51.100" -Longitude "-0.5"
} -Latitude 51.505 -Longitude -0.09 -Zoom 13 -Height '100vh'

Custom Icons

You can specify custom icons for markers using the -Icon parameter.

New-UDMap -Endpoint {
    New-UDMapRasterLayer -TileServer 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png' 
    New-UDMapMarker -Latitude "51.100" -Longitude "-0.5"
} -Latitude 51.505 -Longitude -0.09 -Zoom 13 -Height '100vh' -Icon (New-UDMapIcon -Url = "https://ironmansoftware.com/img/ps-logo.png")
}

Popups

You can create a popup when clicking the marker by using the -Popup parameter and the New-UDMapPopup cmdlet.

New-UDMapMarker -Latitude "51.$RandomLat" -Longitude "-0.$Random" -Popup (
    New-UDMapPopup -Content {
        New-UDAlert -Text "Hello"
    } -MinWidth 200
)

Heatmaps

Heatmaps can be defined by creating a heatmap layer. The intesity and location of the heatmap clusters can be defined by using the New-UDMapHeatmapLayer cmdlet.

New-UDMap -Endpoint {
    New-UDMapRasterLayer -TileServer 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png' 
    New-UDMapHeatmapLayer -Points @(
        @(-37.9019339833, 175.3879181167, "625"),
        @(-37.90920365, 175.4053418167, "397"),
        @(-37.9057407667, 175.39478875, "540"),
        @(-37.9243174333, 175.4220341833, "112"),
        @(-37.8992012333, 175.3666729333, "815"),
        @(-37.9110874833, 175.4102195833, "360"),
        @(-37.9027096, 175.3913196333, "591"),
        @(-37.9011183833, 175.38410915, "655"),
        @(-37.9234701333, 175.4155696333, "181"),
        @(-37.90254175, 175.3926162167, "582"),
        @(-37.92450575, 175.4246711167, "90"),
        @(-37.9242924167, 175.4289432833, "47"),
        @(-37.8986079833, 175.3685293333, "801")
    )
} -Height '100vh'

Marker Clusters

Marker clusters group together markers that are close to each other. As you zoom in or out, the clusters will either combine or explode.

New-UDMap -Endpoint {
    New-UDMapRasterLayer -TileServer 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png' 
    New-UDMapMarkerClusterLayer -Id 'cluster-layer' -Markers @(
        1..100 | ForEach-Object {
            $Random = Get-Random -Minimum 0 -Maximum 100
            $RandomLat = $Random + 400
            New-UDMapMarker -Latitude "51.$RandomLat" -Longitude "-0.$Random"
        }
    )
} -Latitude 51.505 -Longitude -0.09 -Zoom 13 -Height '100vh'

Interactive Maps

Maps provide a series of interactive capabilities for add components to and manipulating the map.

New-UDButton -Text 'Add Circle' -OnClick {
    Add-UDElement -ParentId 'Feature-Group' -Content {
        New-UDMapVectorLayer -Id 'Vectors' -Circle -Latitude 51.505 -Longitude -0.09 -Radius 500 -Color blue -FillColor blue -FillOpacity .5 
    }
}

New-UDButton -Text 'Remove Circle' -OnClick {
    Remove-UDElement -Id 'Vectors' 
}

New-UDButton -Text 'Add Marker' -OnClick {
    Add-UDElement -ParentId 'Feature-Group' -Content {
        New-UDMapMarker -Id 'marker' -Latitude 51.505 -Longitude -0.09 -Popup (
            New-UDMapPopup -Content {
                New-UDCard -Title "Test"
            } -MaxWidth 600
        ) 
    }
}

New-UDButton -Text 'Remove Marker' -OnClick {
    Remove-UDElement -Id 'marker' 
}

New-UDButton -Text 'Add Layer' -OnClick {
    Add-UDElement -ParentId 'layercontrol' -Content {
        New-UDMapOverlay -Id 'MyNewLayer' -Name "MyNewLayer" -Content {
            New-UDMapFeatureGroup -Id 'Feature-Group2' -Content {
                1..100 | % {
                    New-UDMapVectorLayer -Id 'test' -Circle -Latitude "51.$_" -Longitude -0.09 -Radius 50 -Color red -FillColor blue -FillOpacity .5        
                }
            }
        } -Checked

    }
}

New-UDButton -Text 'Remove Layer' -OnClick {
    Remove-UDElement -Id 'MyNewLayer' 
}

New-UDButton -Text 'Move' -OnClick {
    Set-UDElement -Id 'map' -Attributes @{
        latitude = 51.550
        longitude = -0.09
        zoom = 10
    }
}

New-UDButton -Text "Add marker to cluster" -OnClick {
    Add-UDElement -ParentId 'cluster-layer' -Content {
        $Random = Get-Random -Minimum 0 -Maximum 100
        $RandomLat = $Random + 400
        New-UDMapMarker -Latitude "51.$RandomLat" -Longitude "-0.$Random"
    }
}

New-UDButton -Text "Add points to heatmap" -OnClick {
    Add-UDElement -ParentId 'heatmap' -Content {
        @(
            @(51.505, -0.09, "625"),
            @(51.505234, -0.0945654, "625"),
            @(51.50645, -0.098768, "625"),
            @(51.5056575, -0.0945654, "625"),
            @(51.505955, -0.095675, "625"),
            @(51.505575, -0.09657, "625"),
            @(51.505345, -0.099876, "625"),
            @(51.505768, -0.0923432, "625"),
            @(51.505567, -0.02349, "625"),
            @(51.50545654, -0.092342, "625"),
            @(51.5045645, -0.09342, "625")
        )
    }
}

New-UDButton -Text "Clear heatmap" -OnClick {
    Clear-UDElement -Id 'heatmap'
}

New-UDMap -Id 'map' -Endpoint {
    New-UDMapLayerControl -Id 'layercontrol' -Content {
        New-UDMapBaseLayer -Name "Black and White" -Content {
            New-UDMapRasterLayer -TileServer 'https://tiles.wmflabs.org/bw-mapnik/{z}/{x}/{y}.png' 
        } 

        New-UDMapBaseLayer -Name "Mapnik" -Content {
            New-UDMapRasterLayer -TileServer 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png' 
        } 

        New-UDMapBaseLayer -Name "Bing" -Content {
            New-UDMapRasterLayer -Bing -ApiKey 'asdf3rwf34afaw-sdfasdfa23feaw-23424dfsdfa' -Type Road
        } -Checked

        New-UDMapOverlay -Name "Markers" -Content {
            New-UDMapFeatureGroup -Id 'Feature-Group' -Content {
                New-UDMapMarker -Id 'marker' -Latitude 51.505 -Longitude -0.09
            } -Popup (
                New-UDMapPopup -Content {
                    New-UDCard -Title "Test123"
                } -MaxWidth 600
            )
        } -Checked

        New-UDMapOverlay -Name 'Vectors' -Content {
            New-UDMapFeatureGroup -Id 'Vectors' -Content {

            }
        } -Checked

        New-UDMapOverlay -Name "Heatmap" -Content {
            New-UDMapHeatmapLayer -Id 'heatmap' -Points @() 
        } -Checked 

        New-UDMapOverlay -Name "Cluster" -Content {
            New-UDMapMarkerClusterLayer -Id 'cluster-layer' -Markers @(
                1..100 | ForEach-Object {
                    $Random = Get-Random -Minimum 0 -Maximum 100
                    $RandomLat = $Random + 400
                    New-UDMapMarker -Latitude "51.$RandomLat" -Longitude "-0.$Random"
                }
            )
        } -Checked

    }

} -Latitude 51.505 -Longitude -0.09 -Zoom 13 -Height '100vh' -Animate

Feedback

Backdrop

Backdrop component for Universal Apps.

The backdrop component places an overlay over the drop of the entire page. It's useful for displaying loading states.

Basic Backdrop

To create a basic backdrop, you can use the New-UDBackdrop cmdlet and include content to show within the backdrop. The content will be centered on the page. To show the backdrop, use the -Open switch parameter.

New-UDBackdrop -Content {
    New-UDTypography -Text "Loading..." -Variant h2
} -Open

OnClick Handler

The backdrop provides an -OnClick handler that you can use to close the backdrop when clicked. You can use Set-UDElement to open and close the backdrop.

New-UDBackdrop -Id 'backdrop' -Content {
    New-UDTypography -Text "Loading..." -Variant h2
} -Open -OnClick {
    Set-UDElement -Id 'backdrop' -Properties @{
        open = $false
    }
}

API

New-UDBackdrop

Modal

Modal component for Universal Apps.

Modals inform users about a task and can contain critical information, require decisions, or involve multiple tasks.

Basic

New-UDButton -Text 'Basic' -OnClick {
    Show-UDModal -Content {
        New-UDTypography -Text "Hello"
    }
}

Full Screen

New-UDButton -Text 'Full Screen' -OnClick {
    Show-UDModal -Content {
        New-UDTypography -Text "Hello"
    } -Footer {
        New-UDButton -Text "Close" -OnClick { Hide-UDModal }
    }  -FullScreen
}

Full Width

Full width modals take up the full width as defined by the -MaxWidth parameter.

New-UDButton -Text 'Full Width' -OnClick {
    Show-UDModal -Content {
        New-UDTypography -Text "Hello"
    } -FullWidth -MaxWidth 'md'
}

Persistent

Persistent modals do not close when you click off of them. You will have to close it with Hide-UDModal.

New-UDButton -Text 'Persistent' -OnClick {
    Show-UDModal -Content {
        New-UDTypography -Text "Hello"
    } -Footer {
        New-UDButton -Text "Close" -OnClick { Hide-UDModal }
    } -Persistent
}

You can use the Hide-UDModal button to hide a modal that is currently show.

New-UDButton -Text 'Basic' -OnClick {
    Show-UDModal -Content {
        New-UDTypography -Text "Hello"
    }
    Start-Sleep 5
    Hide-UDModal
}

Styling

You can style modules using the -Style, -HeaderStyle, -ContentStyle and -FooterStyle parameters. Style is applied to the entire modal itself and the individual section styles are only applied to those sections. The value for these parameters are hashtables of CSS values.

New-UDButton -Text 'Styling' -OnClick {
    Show-UDModal -Content {
        New-UDTypography -Text "Hello"
    } -Style @{
        backgroundColor = "red"
    }
}

API

Progress

Progress component for Universal Apps

Circular Progress

New-UDProgress -Circular -Color Blue

Linear Indeterminate

New-UDProgress

Linear Determinate

New-UDProgress -PercentComplete 75

API

New-UDProgress

Skeleton

A skeleton component for PowerShell Universal Apps.

A skeleton is a form of a loading component that can show a placeholder while data is received.

Variants

There are three variants that you can use for a skeleton. You can use a circle, text or a rectangle. You can also define the height and width of the skeleton.

New-UDSkeleton
New-UDSkeleton -Variant circle -Width 40 -Height 40
New-UDSkeleton -Variant rect -Width 210 -Height 118

Animations

Skeletons will use the pulsate animation by default. You can also disable animation or use a wave animation.

New-UDSkeleton
New-UDSkeleton -Animation disabled
New-UDSkeleton -Animation wave

API

New-UDSkeleton

Inputs

Input controls for Universal Dashboard

Autocomplete

Autocomplete component for Universal Apps

The autocomplete is a normal text input enhanced by a panel of suggested options.

Static List of Options

Creates a basic autocomplete with a static list of options

Dynamic List of Options

When text is typed, it can be filtered with OnLoadOptions. $Body will contain the current text that is typed.

This example filters the array with Where-Object.

OnChange

$Body contains the currently selected item. The OnChange event will fire when the user selects one or more items.

Icon

You can place an icon before an autocomplete by using the -Icon parameter.

OnEnter

OnEnter is triggered when the user presses the enter key within the autocomplete.

Options

You can use New-UDAutoCompleteOption to specify name and values.

API

Button

Button component for Universal Apps

Buttons allow users to take actions, and make choices, with a single tap.

Contained Button

Contained buttons are high-emphasis, distinguished by their use of elevation and fill. They contain actions that are primary to your app.

Outlined Button

Outlined buttons are medium-emphasis buttons. They contain actions that are important, but aren’t the primary action in an app.

Control Button Size

You can control the pixel size of a button based on pixel size by using the Style parameter

Buttons with icons and label

Sometimes you might want to have icons for certain button to enhance the UX of the application as we recognize logos more easily than plain text. For example, if you have a delete button you can label it with a dustbin icon.

Buttons with event handlers

You can specify a script block to execute when the button is clicked

Loading Button

Loading buttons will display a loading icon while an event handler is running. This is useful for longer running events.

Button Group

A button group produces a button with a drop down menu. This is also referred to a split button.

Disable Button After Click

This example uses Set-UDElement to disable the button after performing an action.

API

Checkbox

Check component for Universal Apps

Checkboxes allow the user to select one or more items from a set.

Checkboxes

Checkboxes can be disabled and checked by default

Checkboxes with custom icon

Create checkboxes that use any icon and style.

Checkboxes with onChange script block

Create checkboxes that fire script blocks when changed.

Checkbox with custom label placement

You can adjust where the label for the checkbox is placed.

Get the value of a Checkbox

You can use Get-UDElement to get the value of the checkbox. Get-UDElement will also return other properties of the checkbox component.

The following example shows a toast message with the value of the checkbox.

API

Code Editor

Code editor component for Universal Apps.

The code editor component allows you to host the editor within your dashboards.

Creating a Code Editor

You can create a new code editor with the New-UDCodeEditor cmdlet. Specifying the -Language parameter will enable syntax highlighting for that language. You will need to specify a height in pixels.

Populating Code

Use the -Code parameter to specify code that will be populated within the code editor when it loads.

Retrieving code from another component

You can retrieve code from another component using the Get-UDElement cmdlet and accessing the code property of the hashtable that is returned.

Setting code from another component

You can set code from another component using the Set-UDElement cmdlet. Specify the code value in a hashtable passed to the -Properties parameter.

Options

The documentation is for an upcoming feature of PowerShell Universal .

The Monaco editor supports a wide range of options. If you wish to use options that aren't available on the New-UDCodeEditor cmdlet, you can use the -Options parameter and pass a hashtable of options instead.

Date Picker

Date Picker component for Universal Apps

Date pickers pickers provide a simple way to select a single value from a pre-determined set.

Date pickers can be used in and .

OnChange Event Handler

The OnChange event handler is called when the date changes. You can access the current date by using the $Body variable.

Variant

You can customize how the date picker is shown. The default is the inline variant that displays the date picker popup in line with the input control. The static variant displays the date picker without having to click anything.

Locale

To set the locate of the date picker, specify the -Locale parameter.

Minimum and Maximum

By default, the user can select any date. To specify minimum and maximum dates, using the -Minimum and -Maximum parameters.

Views

You can limit which portions of the date picker are included by using the -Views parameter. For example, if you wanted to remove the year selector and limit to the current year, you could do the following.

API

Editor

A text editor component for Universal Apps.

The editor component is based on . It's a block editor that accepts text, links, lists, code and images.

When working with the editor, you can receive data about the current document via the OnChange parameter. By default, data is returned in the Editor.js .

Creating an Editor

To create a basic editor, use the New-UDEditor cmdlet.

The editor will be available and you can add new blocks by clicking the plus button.

Working with Data

You can also use the HTML render plugin by specifying the -Format parameter.

To specify the default data for the editor, use the -Data parameter. You need to specify the JSON block format.

Image Support

API

New-UDEditor

Floating Action Button

Floating action button component for Universal Apps

A floating action button (FAB) performs the primary, or most common, action on a screen.

A floating action button appears in front of all screen content, typically as a circular shape with an icon in its center. FABs come in two types: regular, and extended.

Only use a FAB if it is the most suitable way to present a screen’s primary action.

Only one floating action button is recommended per screen to represent the most common action.

Floating Action Button

New-UDFloatingActionButton -Icon (New-UDIcon -Icon user) -Size Small
New-UDFloatingActionButton -Icon (New-UDIcon -Icon user) -Size Medium
New-UDFloatingActionButton -Icon (New-UDIcon -Icon user) -Size Large

OnClick

New-UDFloatingActionButton -Icon (New-UDIcon -Icon user) -OnClick {
    Show-UDToast -Message "Hello!"
}

API

New-UDFloatingActionButton

Form

Form component for Universal Apps

Forms provide a way to collect data from users.

Forms can include any type of control you want. This allows you to customize the look and feel and use any input controls.

Data entered via the input controls will be sent back to the the OnSubmit script block when the form is submitted. Within the OnSubmit event handler, you will access to the $EventData variable that will contain properties for each of the fields in the form.

For example, if you have two fields, you will have two properties on $EventData.

New-UDForm -Content {
    New-UDTextbox -Id 'txtTextField'
    New-UDCheckbox -Id 'chkCheckbox'
} -OnSubmit {
    Show-UDToast -Message $EventData.txtTextField
    Show-UDToast -Message $EventData.chkCheckbox
}

Supported Controls

The following input controls automatically integrate with a form. The values that are set within these controls will be sent during validation and in the OnSubmit event handler.

Autocomplete
Checkbox
Date Picker
Radio
Select
Slider
Switch
Textbox
Time Picker
Transfer List
Upload

Simple Form

Simple forms can use inputs like text boxes and checkboxes.

New-UDForm -Content {
    New-UDTextbox -Id 'txtTextfield'
    New-UDCheckbox -Id 'chkCheckbox'
} -OnSubmit {
    Show-UDToast -Message $EventData.txtTextfield
    Show-UDToast -Message $EventData.chkCheckbox
}

Formatting a Form

Since forms can use any component, you can use standard formatting components within the form.

New-UDForm -Content {

    New-UDRow -Columns {
        New-UDColumn -SmallSize 6 -LargeSize 6 -Content {
            New-UDTextbox -Id 'txtFirstName' -Label 'First Name' 
        }
        New-UDColumn -SmallSize 6 -LargeSize 6 -Content {
            New-UDTextbox -Id 'txtLastName' -Label 'Last Name'
        }
    }

    New-UDTextbox -Id 'txtAddress' -Label 'Address'

    New-UDRow -Columns {
        New-UDColumn -SmallSize 6 -LargeSize 6  -Content {
            New-UDTextbox -Id 'txtState' -Label 'State'
        }
        New-UDColumn -SmallSize 6 -LargeSize 6  -Content {
            New-UDTextbox -Id 'txtZipCode' -Label 'ZIP Code'
        }
    }

} -OnSubmit {
    Show-UDToast -Message $EventData.txtFirstName
    Show-UDToast -Message $EventData.txtLastName
}

Returning Components

When a form is submitted, you can optionally return another component to replace the form on the page. You can return any Universal Dashboard component. All you need to do is ensure that the component is written to the pipeline within the OnSubmit event handler.

New-UDForm -Content {
    New-UDTextbox -Id 'txtTextfield'
} -OnSubmit {
    New-UDTypography -Text $EventData.txtTextfield
}

Validating a Form

Form validation can be accomplished by using the OnValidate script block parameter.

New-UDForm -Content {
    New-UDTextbox -Id 'txtValidateForm'
} -OnValidate {
    $FormContent = $EventData

    if ($FormContent.txtValidateForm -eq $null -or $FormContent.txtValidateForm -eq '') {
        New-UDFormValidationResult -ValidationError "txtValidateForm is required"
    } else {
        New-UDFormValidationResult -Valid
    }
} -OnSubmit {
    Show-UDToast -Message $Body
}

Canceling a Form

You can define an -OnCancel event handler to invoke when the cancel button is pressed. This can be used to take actions like close a modal.

New-UDButton -Text 'On Form' -OnClick {
    Show-UDModal -Content {
        New-UDForm -Content {
            New-UDTextbox -Label 'Hello'
        } -OnSubmit {
            Show-UDToast -Message 'Submitted!'
            Hide-UDModal
        } -OnCancel {
            Hide-UDModal
        }
    }
}

Displaying output without Replacing the form

Although you can return components directly from a form, you may want to retain the form so users can input data again. To do so, you can use Set-UDElement and a placeholder element that you can set the content to.

In this example, we have an empty form that, when submitted, will update the results element with a UDCard.

New-UDForm -Content {

} -OnSubmit {
   Set-UDElement -Id 'results' -Content {
      New-UDCard -Content { "Hello " + (Get-Date) }
   }
}

New-UDElement -Id 'results' -Tag 'div'

Schema Forms

Instead of defining all the layout and logic for forms using cmdlets, you can also define a form based on a hashtable of schema. This version of forms is based on react-jsonschema-form.

Fields

You define fields that accept string, number, integer, enum and boolean types. This changes the type of input shown.

New-UDForm -Schema @{
   title = "Test Form"
   type = "object"
   properties = @{
       name = @{
           type = "string"
       }
       age = @{
           type = "number"
       }
   }
} -OnSubmit {
   # $EventData.name
   # $EventData.age
}

Required Properties

You can use the required property to set a list of required properties.

New-UDForm -Schema @{
   title = "Test Form"
   type = "object"
   properties = @{
       name = @{
           type = "string"
       }
       age = @{
           type = "number"
       }
   }
   required = @('name')
} -OnSubmit {
   # $EventData.name
   # $EventData.age
}

Note that the properties need to be lower case! For example, you need to ensure the keys in your properties hashtable are lower case and the list of required properties are also lower case.

Ordering

You can use the schemaUI property to modify the ordering of the fields.

New-UDForm -Schema @{
        title = "Test"
        type = "object"
        properties = @{
            hostname = @{
                title = "Hostname"
                type = "string"
                }
            ipaddress= @{
                title = "IP Address"
                type = "string"
                format = "ipv4"
                }
            description = @{
                title = "Server Description"
                type = "string"
                }
            servertype = @{
                title = "Server Type"
                type = "string"                            
                enum = "App","DB"
                }
            environment = @{
                title = "Environment"
                type = "string"
                enum = "Prod", "Dev" , "QA"
                }
            }
		required = @('hostname','ipaddress','description','servertype','environment')                    
	} -uiSchema @{
		"ui:order" = @('environment','hostname','ipaddress','description')
	} -OnSubmit {
		Show-UDModal -Content {                        
			New-UDTypography -Text $EventData
		} -Footer {
			New-UDButton -Text "Close" -OnClick {Hide-UDModal}
		} -Persistent
	}

Arrays

You can create forms that accept 0 to many objects. The user will be able to add and remove objects to the form.

New-UDForm -Schema @{
   title = "Test Form"
   type = "array"
   items = @{
      type = "object" 
       properties = @{
           name = @{
               type = "string"
           }
           age = @{
               type = "number"
           }
       }
   }
} -OnSubmit {
   # $EventData[0].name
   # $EventData[0].age
}

Script Forms

You can automatically generate forms based on scripts in your PowerShell Universal environment. Script forms will generate input components based on the param block. Script forms automatically support progress and feedback.

Script forms also support displaying the output as text or a table.

New-UDForm -Script "Script.ps1" -OutputType 'text'

API

Radio

Radio component for Universal Apps

Radio buttons allow the user to select one option from a set.

Use radio buttons when the user needs to see all available options. If available options can be collapsed, consider using a dropdown menu because it uses less space.

Radio buttons should have the most commonly used option selected by default.

Simple Radio

New-UDRadioGroup -Label "Day" -Content {
    New-UDRadio -Label Monday -Value 'monday'
    New-UDRadio -Label Tuesday -Value 'tuesday'
    New-UDRadio -Label Wednesday -Value 'wednesday'
    New-UDRadio -Label Thursday -Value 'thursday'
    New-UDRadio -Label Friday  -Value 'friday'
    New-UDRadio -Label Saturday -Value 'saturday'
    New-UDRadio -Label Sunday -Value 'sunday'
}

OnChange

An event handler that is called when the radio group is changed. the $Body variable will contain the current value.

New-UDRadioGroup -Label "Day" -Content {
    New-UDRadio -Label Monday -Value 'monday'
    New-UDRadio -Label Tuesday -Value 'tuesday'
    New-UDRadio -Label Wednesday -Value 'wednesday'
    New-UDRadio -Label Thursday -Value 'thursday'
    New-UDRadio -Label Friday  -Value 'friday'
    New-UDRadio -Label Saturday -Value 'saturday'
    New-UDRadio -Label Sunday -Value 'sunday'
} -OnChange { Show-UDToast -Message $Body }
    }

Default Value

Set the default value of the radio group.

New-UDRadioGroup -Label "Day" -Content {
    New-UDRadio -Label Monday -Value 'monday'
    New-UDRadio -Label Tuesday -Value 'tuesday'
    New-UDRadio -Label Wednesday -Value 'wednesday'
    New-UDRadio -Label Thursday -Value 'thursday'
    New-UDRadio -Label Friday  -Value 'friday'
    New-UDRadio -Label Saturday -Value 'saturday'
    New-UDRadio -Label Sunday -Value 'sunday'
} -Value 'sunday'

Custom Formatting

You can use custom formatting within the radio group. The below example will place the radio buttons next to each other instead of on top of each other.

New-UDRadioGroup -Label "Day" -Content {
    New-UDRow -Columns {
        New-UDColumn -LargeSize 1 -Content {
            New-UDRadio -Label Monday -Value 'monday'        
        }
        New-UDColumn -LargeSize 1 -Content {
            New-UDRadio -Label Sunday -Value 'sunday'
        }
    }
}

API

Rating

Rating input component.

Basic Rating

New-UDRating

OnChange

Take action when the rating is changed.

New-UDRating -OnChange {
    Show-UDToast $EventData
}

Maximum

Change the maximum rating.

New-UDRating -Max 10

Precision

Change the precision for ratings.

New-UDRating -Precision .5

Size

Change the size of the rating icons.

New-UDRating -Size large

Select

Select component for Universal Apps

Select components are used for collecting user provided information from a list of options.

Simple Select

Create a simple select with multiple options.

New-UDSelect -Option {
    New-UDSelectOption -Name 'One' -Value 1
    New-UDSelectOption -Name 'Two' -Value 2
    New-UDSelectOption -Name 'Three' -Value 3
}

Grouped Select

Create a select with groups of selections.

New-UDSelect -Option {
    New-UDSelectGroup -Name 'Group One' -Option {
        New-UDSelectOption -Name 'One' -Value 1
        New-UDSelectOption -Name 'Two' -Value 2
        New-UDSelectOption -Name 'Three' -Value 3
    }
    New-UDSelectGroup -Name 'Group Two' -Option {
        New-UDSelectOption -Name 'Four' -Value 4
        New-UDSelectOption -Name 'Five' -Value 5
        New-UDSelectOption -Name 'Size' -Value 6
    }
}

OnChange

Execute a PowerShell event handler when the value of the select is changed. $EventData[0] for the single item that was selected.

New-UDSelect -Option {
    New-UDSelectOption -Name 'One' -Value 1
    New-UDSelectOption -Name 'Two' -Value 2
    New-UDSelectOption -Name 'Three' -Value 3
} -OnChange { Show-UDToast -Message $EventData[0] }

Multiple Select

Execute a PowerShell event handler when the more than one value of the select is changed. $EventData is an array of the selected items.

New-UDSelect -Multiple -Option {
    New-UDSelectOption -Name 'One' -Value 1
    New-UDSelectOption -Name 'Two' -Value 2
    New-UDSelectOption -Name 'Three' -Value 3
} -OnChange { 
    Show-UDToast -Message (ConvertTo-json -InputObject $EventData) 
}

Get-UDElement

Retrieve the value of the select from another component.

  New-UDSelect -Option {
      New-UDSelectOption -Name 'One' -Value 1
      New-UDSelectOption -Name 'Two' -Value 2
      New-UDSelectOption -Name 'Three' -Value 3
  } -Id 'select' -DefaultValue 2

  New-UDButton  -Text 'OnBoard' -OnClick {
    $Element = Get-UDElement -Id 'select'
    if ($Element.Value)
    {
      Show-UDToast -Message $Element.Value
    }
    else 
    {
      Show-UDToast -Message $Element.DefaultValue
    }
  }

API

Slider

Slider component for Universal Apps.

Sliders allow users to make selections from a range of values.

Sliders reflect a range of values along a bar, from which users may select a single value. They are ideal for adjusting settings such as volume, brightness, or applying image filters.

Slider

New-UDSlider -Value 1

Slider with minimum and maximum values

New-UDSlider -Min 10 -Max 1000

Disabled Slider

New-UDSlider -Disabled

Slider with custom step size

New-UDSlider -Min 10 -Max 1000 -Step 100

Slider with marks

New-UDSlider -Marks

Range based slider

New-UDSlider -Value @(1, 10)

OnChange event for slider

New-UDSlider -OnChange {
    Show-UDToast -Message $Body 
    Set-TestData $Body
}

API

New-UDSlider

Switch

Switch component for Universal Apps

Switches toggle the state of a single setting on or off.

Switches are the preferred way to adjust settings on mobile. The option that the switch controls, as well as the state it’s in, should be made clear from the corresponding inline label.

Switch

Create a basic switch.

OnChange Event

Respond to when a switch value is changed. The $EventData variable will include whether or not the switch was checked or unchecked.

Get-UDElement Support

You can retrieve the value of the switch within another component by using Get-UDElement. Use the Checked property to determine whether the switch is checked out not.

API

Textbox

Textbox component for Universal Apps

A textbox lets users enter and edit text.

Textbox

Password Textbox

A password textbox will mask the input.

Multiline

You can create a multiline textbox by using the -Multiline parameter. Pressing enter will add a new line. You can define the number of rows and the max number of rows using -Rows and -RowsMax.

Interaction

Retrieving a textbox value

You can use Get-UDElement to get the value of a textbox

Setting the textbox value

Icons

You can set the icon of a textbox by using the -Icon parameter and the New-UDIcon cmdlet.

Mask

The textbox mask is accomplished using react-imask. You can specify RegEx and pattern matching.

This example creates a mask for US based phone numbers.

Unmasking

The default behavior of -Mask is to return the masked value in forms and Get-UDElement. You can return the unmasked value by specifying the -Unmask parameter.

OnEnter

The -OnEnter event handler is executed when the user presses enter in the text field. It is useful for performing other actions, like clicking a button, on enter.

OnBlur

The -OnBlur event handler is executed when the textbox loses focus.

OnValidate

Use the -OnValidate event handler to validate input typed in the textbox.

API

Time Picker

Time picker component for Universal Apps

Time pickers pickers provide a simple way to select a single value from a pre-determined set.

Time Picker

Locale

Specify the locale of the time picker.

24-Hour Time

You can use the -DisableAmPm parameter to use 24-hour time.

API

Transfer List

A transfer list (or "shuttle") enables the user to move one or more list items between lists.

Simple Transfer List

Create a simple transfer list.

Transfer List Value on Change

Use the OnChange event handler to get the value of the selected items.

Transfer List in a Form

Transfer lists can be used within forms and steppers.

API

Upload

Component for uploading files in Universal Apps.

The UDUpload component is used to upload files to Universal Apps. You can process files the user uploads. You will receive the data for the file, a file name and the type of file if it can be determined by the web browser.

This component works with and .

Upload ony supports files up to 2 GB in size.

Uploading a File

Uploads a file and shows the contents via a toast.

The body of the OnUpload script block is a JSON string with the following format.

The $EventData is an object with the following structure.

Uploading a File with a Form

Uploads a file as part of a UDForm.

The body of the OnSubmit script block is the same one you will see with any form and the file will be contains as one of the fields within the form.

Example: Uploading a file and save to it the temp directory

This example allows a user to upload a file. Once the file is uploaded, it will be saved to the temporary directory.

API

Navigation

Drawer

Drawer component for Universal Apps

Permanent Drawer

A permanent drawer will be shown at all times. By default, it is show on the left side of the screen.

API

Layout

Utilities

Surfaces

Table

Table component for Universal Apps

Tables display sets of data. They can be fully customized.

Tables display information in a way that’s easy to scan, so that users can look for patterns and insights. They can be embedded in primary content, such as cards.

Simple Table

A simple example with no frills. Table columns are defined from the data.

$Data = @(
    @{Dessert = 'Frozen yoghurt'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Ice cream sandwich'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Eclair'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Cupcake'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Gingerbread'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
)

New-UDTable -Data $Data

Table with Custom Columns

Define custom columns for your table.

$Data = @(
    @{Dessert = 'Frozen yoghurt'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Ice cream sandwich'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Eclair'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Cupcake'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Gingerbread'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
) 

$Columns = @(
    New-UDTableColumn -Property Dessert -Title "A Dessert"
    New-UDTableColumn -Property Calories -Title Calories 
    New-UDTableColumn -Property Fat -Title Fat 
    New-UDTableColumn -Property Carbs -Title Carbs 
    New-UDTableColumn -Property Protein -Title Protein 
)

New-UDTable -Id 'customColumnsTable' -Data $Data -Columns $Columns

Table with Custom Column Rendering

Define column rendering. Sorting and exporting still work for the table.

$Data = @(
    @{Dessert = 'Frozen yoghurt'; Calories = 1; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Ice cream sandwich'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Eclair'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Cupcake'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Gingerbread'; Calories = 200; Fat = 6.0; Carbs = 24; Protein = 4.0}
) 

$Columns = @(
    New-UDTableColumn -Property Dessert -Title Dessert -Render { 
        New-UDButton -Id "btn$($EventData.Dessert)" -Text "Click for Dessert!" -OnClick { Show-UDToast -Message $EventData.Dessert } 
    }
    New-UDTableColumn -Property Calories -Title Calories 
    New-UDTableColumn -Property Fat -Title Fat 
    New-UDTableColumn -Property Carbs -Title Carbs 
    New-UDTableColumn -Property Protein -Title Protein 
)

New-UDTable -Data $Data -Columns $Columns -Sort -Export

Table Column Width

Column width can be defined using the -Width parameter. You can also decide to truncate columns that extend past that width.

$Data = @(
    @{Dessert = 'Frozen yoghurt'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Ice cream sandwich'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Eclair'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Cupcake'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Gingerbread'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
) 

$Columns = @(
    New-UDTableColumn -Property Dessert -Title Dessert -Render { 
        New-UDButton -Id "btn$($EventData.Dessert)" -Text "Click for Dessert!" -OnClick { Show-UDToast -Message $EventData.Dessert } 
    }
    New-UDTableColumn -Property Calories -Title Calories -Width 5 -Truncate
    New-UDTableColumn -Property Fat -Title Fat 
    New-UDTableColumn -Property Carbs -Title Carbs 
    New-UDTableColumn -Property Protein -Title Protein 
)

New-UDTable -Data $Data -Columns $Columns -Sort

Filters

You can configure custom filters per column. The table supports text, select, fuzzy , slider, range, date , number, and autocomplete filters.

$Data = @(
    @{Dessert = 'Frozen yoghurt'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Ice cream sandwich'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Eclair'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Cupcake'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Gingerbread'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
) 

$Columns = @(
    New-UDTableColumn -Property Dessert -Title "A Dessert" -Filter -FilterType AutoComplete
    New-UDTableColumn -Property Calories -Title Calories -Filter -FilterType Range
    New-UDTableColumn -Property Fat -Title Fat -Filter -FilterType Range
    New-UDTableColumn -Property Carbs -Title Carbs -Filter -FilterType Range
    New-UDTableColumn -Property Protein -Title Protein -Filter -FilterType Range
)

New-UDTable -Id 'customColumnsTable' -Data $Data -Columns $Columns -ShowFilter

Static Options for Select Filters

When using server-side processing, the available filters may not display the full range of options since the select dropdown only has access to the current page of results. To avoid this, you can use the -Options parameter on New-UDTableColumn.

New-UDTableColumn -Property Dessert -Title 'Dessert' -Filter -FilterType 'Select' -Options @('Frozen yoghurt', 'Eclair', 'Cupcake')

Search

To enable search, use the -ShowSearch parameter on New-UDTable.

$Data = @(
    @{Dessert = 'Frozen yoghurt'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Ice cream sandwich'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Eclair'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Cupcake'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Gingerbread'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
)

New-UDTable -Data $Data -ShowSearch

When using custom columns, you will need to add the -IncludeInSearch parameter to the columns you'd like to include in the search.

$Data = @(
    @{Dessert = 'Frozen yoghurt'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Ice cream sandwich'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Eclair'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Cupcake'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Gingerbread'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
) 

$Columns = @(
    New-UDTableColumn -Property Dessert -Title "A Dessert" -IncludeInSearch
    New-UDTableColumn -Property Calories -Title Calories 
    New-UDTableColumn -Property Fat -Title Fat 
    New-UDTableColumn -Property Carbs -Title Carbs 
    New-UDTableColumn -Property Protein -Title Protein 
)

New-UDTable -Id 'customColumnsTable' -Data $Data -Columns $Columns -ShowSearch

Table with server-side processing

Process data on the server so you can perform paging, filtering, sorting and searching in systems like SQL. To implement a server-side table, you will use the -LoadData parameter. This parameter accepts a ScriptBlock. The $EventData variable includes information about the state of the table. You can use cmdlets to process the data based on this information.

$EventData Structure

The $EventData object contains the following properties.

Property Name

Type

Description

Filters

Hashtable[] @{ id = 'fieldName'

value = 'filterValue' }

A list of filter values. Each hashtable has an Id and a Value property.

OrderBy

Hashtable @{ field = "fieldName" }

Property name to sort by.

OrderDirection

string

asc or desc depending on the sort order.

Page

int

The current page (starting with 0).

PageSize

int

The selected page size.

Properties

string[]

An array of properties being shown in the table.

string

A search string provided by the user.

TotalCount

int

The total number of records before filtering or paging.

Example

$Columns = @(
    New-UDTableColumn -Property Name -Title "Name" -ShowFilter
    New-UDTableColumn -Property Value -Title "Value" -ShowFilter
)

$Data = 1..1000 | ForEach-Object {
  [PSCustomObject]@{
      Name = "Record-$_"
      Value = $_ 
  }
}

New-UDTable -Columns $Columns -LoadData {
    foreach($Filter in $EventData.Filters)
    {
        $Data = $Data | Where-Object -Property $Filter.Id -Match -Value $Filter.Value
    }
    
    if ($EventData.Search)
    {
        $Data = $Data | Where-Object { $_.Name -match $EventData.Search -or $_.Value -match $EventData.Search }
    }

    $TotalCount = $Data.Count 

    if (-not [string]::IsNullOrEmpty($EventData.OrderBy.Field))
    {
        $Descending = $EventData.OrderDirection -ne 'asc'
        $Data = $Data | Sort-Object -Property ($EventData.orderBy.Field) -Descending:$Descending
    }
    
    $Data = $Data | Select-Object -First $EventData.PageSize -Skip ($EventData.Page * $EventData.PageSize)

    $Data | Out-UDTableData -Page $EventData.Page -TotalCount $TotalCount -Properties $EventData.Properties 
} -ShowFilter -ShowSort -ShowPagination

Retrieving Displayed Data

You may want to allow the user to take action on the current set of displayed data. To do so, use Get-UDElement in the input object you want to retrieve the data from and get the table by Id. Once you have the element, you can use the Data property of the element to get an array of currently displayed rows.

$Columns = @(
    New-UDTableColumn -Property Name -Title "Name" -ShowFilter
    New-UDTableColumn -Property Value -Title "Value" -ShowFilter
)

$Data = 1..1000 | ForEach-Object {
  @{
      Name = "Record-$_"
      Value = $_ 
  }
}

New-UDButton -Text 'Get Filtered Data' -OnClick {
    $Element = Get-UDElement -Id 'filteredTable'
    Show-UDModal -Content {
        New-UDElement -Tag 'pre' -Content {
           $Element | ConvertTo-Json
        }
    }
}

New-UDTable -Id 'filteredTable' -Columns $Columns -LoadData {
    foreach($Filter in $EventData.Filters)
    {
        $Data = $Data | Where-Object -Property $Filter.Id -Match -Value $Filter.Value
    }

    $TotalCount = $Data.Count 

    if (-not [string]::IsNullOrEmpty($EventData.OrderBy))
    {
        $Descending = $EventData.OrderDirection -ne 'asc'
        $Data = $Data | Sort-Object -Property $EventData.orderBy -Descending:$Descending
    }
    
    $Data = $Data | Select-Object -First $EventData.PageSize -Skip ($EventData.Page * $EventData.PageSize)

    $Data | Out-UDTableData -Page $EventData.Page -TotalCount $TotalCount -Properties $EventData.Properties 
} -ShowFilter -ShowSort -ShowPagination

Paging

By default, paging is disable and tables will grow based on how many rows of data you provide. You can enable paging by using the -ShowPagination cmdlet (alias -Paging). You can configure the page size using the -PageSize cmdlet.

$Data = @(
    @{Dessert = 'Frozen yoghurt'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Ice cream sandwich'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Eclair'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Cupcake'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Gingerbread'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
) 

New-UDTable -Data $Data -Paging -PageSize 2

Disable Page Size All

By default, the page size selector provides an option to show all rows. If you want to prevent users from doing this, use the -DisablePageSizeAll cmdlet.

Pagination Location

You can change the location of the pagination control by using the -PaginationLocation parameter. It accepts top, bottom and both.

Page Sizes

The page size, by default, is set to 5. Users can adjust the number of rows per page by using the Rows per page drop down. You can adjust the default page size by using the -PageSize parameter. To adjust the values available within the Rows per page drop down, you can use an array of integers pass to the -PageSizeOptions parameter.

$Data = @(
    @{Dessert = 'Frozen yoghurt'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Ice cream sandwich'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Eclair'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Cupcake'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Gingerbread'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
) 

New-UDTable -Data $Data -Paging -PageSize 2 -PageSizeOptions @(2, 4, 6)

Sorting

To enable sorting for a table, use the -ShowSort parameter. When you enable sorting, you will be able to click the table headers to sort the table by clicking the headers. By default, multi-sort is enabled. To multi-hold shift and click a column header.

$Data = @(
    @{Dessert = 'Frozen yoghurt'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Ice cream sandwich'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Eclair'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Cupcake'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Gingerbread'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
) 

New-UDTable -Data $Data -ShowSort

You can control which columns can be sorted by using New-UDTableColumn and -ShowSort parameter.

    @{Dessert = 'Eclair'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Cupcake'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Gingerbread'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
) 

$Columns = @(
    New-UDTableColumn -Property Dessert -Title "A Dessert" -ShowSort
    New-UDTableColumn -Property Calories -Title Calories 
    New-UDTableColumn -Property Fat -Title Fat 
    New-UDTableColumn -Property Carbs -Title Carbs -ShowSort
    New-UDTableColumn -Property Protein -Title Protein -ShowSort
)

New-UDTable -Id 'customColumnsTable' -Data $Data -Columns $Columns

Disable Sort Remove

By default, the sorting of a table has 3 states. Unsorted, ascending and descending. If you would like to disable the unsorted state, use the -DisableSortRemove parameter of New-UDTable.

$Data = @(
    @{Dessert = 'Frozen yoghurt'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Ice cream sandwich'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Eclair'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Cupcake'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Gingerbread'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
) 

New-UDTable -Data $Data -ShowSort -DisableSortRemove

Selection

Tables support selection of rows. You can create an event handler for the OnRowSelected parameter to receive when a new row is selected or unselected or you can use Get-UDElement to retrieve the current set of selected rows.

The following example creates a table with row selection enabled. A toast is show when clicking the row or when clicking the GET Rows button.

$Data = try { get-service -ea Stop | select Name,@{n = "Status";e={ $_.Status.ToString()}},@{n = "StartupType";e={ $_.StartupType.ToString()}},@{n = "StartType";e={ $_.StartType.ToString()}} } catch {}
$Columns = @(
    New-UDTableColumn -Property Name -Title "Service Name" -ShowSort -IncludeInExport -IncludeInSearch -ShowFilter -FilterType text
    New-UDTableColumn -Property Status -Title Status -ShowSort -DefaultSortColumn -IncludeInExport -IncludeInSearch -ShowFilter -FilterType select 
    New-UDTableColumn -Property StartupType -Title StartupType -IncludeInExport -ShowFilter -FilterType select
    New-UDTableColumn -Property StartType -Title StartType -IncludeInExport -ShowFilter -FilterType select 
)
New-UDTable -Id 'service_table' -Data $Data -Columns $Columns -Title 'Services' -ShowSearch -ShowPagination -ShowSelection -Dense -OnRowSelection {
    $Item = $EventData
    Show-UDToast -Message "$($Item | out-string)"
}
New-UDButton -Text "GET Rows" -OnClick {
    $value = Get-UDElement -Id "service_table"
    Show-UDToast -Message "$( $value.selectedRows | Out-String )"
}

The $EventData variable for the -OnRowSelected event will include all the columns as properties and a selected property as to whether the row was selected or unselected.

For example, the service table data would look like this.

@{
   Id = 0
   Name = 'AESMService',
   Status = 'Running'
   StartupType = 'AutomaticDelayedStart'
   StartType = 'Automation'
   selected = $true
}

Collapsible Rows

You can include additional information within the table by using the -OnRowExpand parameter of New-UDTable. It accepts a ScriptBlock that you can use to return additional components.

New-UDTable -Data (Get-Service) -OnRowExpand {
    New-UDAlert -Text $EventData.DisplayName
} -Columns @(
    New-UDTableColumn -Title 'Name' -Property 'Name'
    New-UDTableColumn -Title 'Status' -Property 'Status'
)

Exporting

Tables support exporting the data within the table. You can export as CSV, XLSX, JSON or PDF. You can define which columns to include in an export and choose to export just the current page or all the data within the table.

$Data = try { get-service -ea Stop | select Name,@{n = "Status";e={ $_.Status.ToString()}},@{n = "StartupType";e={ $_.StartupType.ToString()}},@{n = "StartType";e={ $_.StartType.ToString()}} } catch {}
$Columns = @(
    New-UDTableColumn -Property Name -Title "Service Name" -IncludeInExport
    New-UDTableColumn -Property Status -Title Status 
    New-UDTableColumn -Property StartupType
    New-UDTableColumn -Property StartType -IncludeInExport
)
New-UDTable -Id 'service_table' -Data $Data -Columns $Columns -Title 'Services' -ShowSearch -ShowPagination -Dense -Export

Hidden Columns

Hidden columns allow you to include data that is not displayed in the table but is included in the exported data.

The following hides the StartType column from the user but includes it in the export.

$Data = try { get-service -ea Stop | select Name,@{n = "Status";e={ $_.Status.ToString()}},@{n = "StartupType";e={ $_.StartupType.ToString()}},@{n = "StartType";e={ $_.StartType.ToString()}} } catch {}
$Columns = @(
    New-UDTableColumn -Property Name -Title "Service Name" -IncludeInExport
    New-UDTableColumn -Property Status -Title Status 
    New-UDTableColumn -Property StartupType
    New-UDTableColumn -Property StartType -IncludeInExport -Hidden
)
New-UDTable -Id 'service_table' -Data $Data -Columns $Columns -Title 'Services' -ShowSearch -ShowPagination -Dense -Export

Server-Side Exporting

You can control the export functionality with a PowerShell script block. This is useful when exporting from server-side sources like SQL server tables.

In this example, I have a SQL table that contains podcasts. When exporting, you will receive information about the current state of the table to allow you to customize what data is exported.

$Columns = @(
    New-UDTableColumn -Property Name -Title "Name" -ShowFilter -IncludeInExport
    New-UDTableColumn -Property Value -Title "Value" -ShowFilter -IncludeInExport
)

$Data = 1..1000 | ForEach-Object {
  [PSCustomObject]@{
      Name = "Record-$_"
      Value = $_ 
  }
}

New-UDTable -Columns $Columns -LoadData {
    foreach($Filter in $EventData.Filters)
    {
        $Data = $Data | Where-Object -Property $Filter.Id -Match -Value $Filter.Value
    }

    $TotalCount = $Data.Count 

    if (-not [string]::IsNullOrEmpty($EventData.OrderBy.Field))
    {
        $Descending = $EventData.OrderDirection -ne 'asc'
        $Data = $Data | Sort-Object -Property ($EventData.orderBy.Field) -Descending:$Descending
    }
    
    $Data = $Data | Select-Object -First $EventData.PageSize -Skip ($EventData.Page * $EventData.PageSize)

    $Data | Out-UDTableData -Page $EventData.Page -TotalCount $TotalCount -Properties $EventData.Properties 
} -ShowFilter -ShowSort -ShowPagination  -Export -OnExport {
   $Query = $Body | ConvertFrom-Json

        <# Query will contain
            filters: []
            orderBy: undefined
            orderDirection: ""
            page: 0
            pageSize: 5
            properties: (5) ["dessert", "calories", "fat", "carbs", "protein"]
            search: ""
            totalCount: 0
            allRows: true
        #>

    $Data | ConvertTo-Json
}

Customizing Export Options

You can decide which export options to present to your users using the -ExportOption cmdlet. The following example would only show the CSV export option.

$Data = try { get-service -ea Stop | select Name,@{n = "Status";e={ $_.Status.ToString()}},@{n = "StartupType";e={ $_.StartupType.ToString()}},@{n = "StartType";e={ $_.StartType.ToString()}} } catch {}
$Columns = @(
    New-UDTableColumn -Property Name -Title "Service Name" -IncludeInExport
    New-UDTableColumn -Property Status -Title Status 
    New-UDTableColumn -Property StartupType
    New-UDTableColumn -Property StartType -IncludeInExport
)
New-UDTable -Id 'service_table' -Data $Data -Columns $Columns -Title 'Services' -ShowSearch -ShowPagination -Dense -Export -ExportOption "csv"

Customizing Labels

You can use the -TextOption parameter along with the New-UDTableTextOption cmdlet to set text fields within the table.

$Data = @(
    @{Dessert = 'Frozen yoghurt'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Ice cream sandwich'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Eclair'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Cupcake'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
    @{Dessert = 'Gingerbread'; Calories = 159; Fat = 6.0; Carbs = 24; Protein = 4.0}
) 

$Option = New-UDTableTextOption -Search "Search all these records"

New-UDTable -Data $Data -TextOption $Option -ShowSearch

Refresh with a button

Data Parameter

You can externally refresh a table by putting the table within a dynamic region and using Sync-UDElement.

This example creates a button to refresh the table.

New-UDDynamic -Id 'table' -Content {
    $Data = @(
        @{ Random = Get-Random }
        @{ Random = Get-Random }
        @{ Random = Get-Random }
        @{ Random = Get-Random }
        @{ Random = Get-Random }
    )
    
    # Store in the page so we can get the current ID. 
    # Using the same ID fails to update when the dynamic reloads.
    $Page:Table = New-UDTable -Data $Data -Paging -ShowSelection
    $Page:Table
} 

New-UDButton -Text 'Refresh Table' -OnClick {
    Sync-UDElement -Id 'table'
}

New-UDButton -Text 'Get Data' -OnClick {
    Show-UDToast (Get-UDElement -Id $Page:Table.Id | ConvertTo-Json)
}

LoadData Parameter

If you use the -LoadData parameter, you can sync the table directly. This has the benefit of maintaining the table state, such as the page and filtering, after the refresh.

New-UDButton -Text 'Table1' -OnClick { Sync-UDElement -Id 'Table1' }

$Columns = @(
    New-UDTableColumn -Property Name -Title "Name" -ShowFilter -Render { $EventData.Name }
    New-UDTableColumn -Property Value -Title "Value" -ShowFilter
)

New-UDTable -Columns $Columns -LoadData {
    $Data = 1..1000 | ForEach-Object {
        @{
            Name = "Record-$_"
            Value = $_ 
        }
    }
    
    foreach($Filter in $EventData.Filters)
    {
        $Data = $Data | Where-Object -Property $Filter.Id -Match -Value $Filter.Value
    }

    $TotalCount = $Data.Count 

    if (-not [string]::IsNullOrEmpty($EventData.OrderBy))
    {
        $Descending = $EventData.OrderDirection -ne 'asc'
        $Data = $Data | Sort-Object -Property $EventData.orderBy -Descending:$Descending
    }
    
    $Data = $Data | Select-Object -First $EventData.PageSize -Skip ($EventData.Page * $EventData.PageSize)

    $Data | Out-UDTableData -Page $EventData.Page -TotalCount $TotalCount -Properties $EventData.Properties 
} -ShowFilter -ShowSort -ShowPagination  -Id 'Table1'

Show Refresh Button

You can use the -ShowRefresh parameter to provide a refresh button for server-side tables.

$Columns = @(
    New-UDTableColumn -Property Dessert -Title "A Dessert"
    New-UDTableColumn -Property Calories -Title Calories 
    New-UDTableColumn -Property Fat -Title Fat 
    New-UDTableColumn -Property Carbs -Title Carbs 
    New-UDTableColumn -Property Protein -Title Protein 
)

New-UDTable -ShowRefresh -Columns $Columns -LoadData {
    $Query = $Body | ConvertFrom-Json

    <# Query will contain
        filters: []
        orderBy: undefined
        orderDirection: ""
        page: 0
        pageSize: 5
        properties: (5) ["dessert", "calories", "fat", "carbs", "protein"]
        search: ""
        totalCount: 0
    #>

    @(
        @{Dessert = 'Frozen yoghurt'; Calories = (Get-Random); Fat = 6.0; Carbs = 24; Protein = 4.0}
        @{Dessert = 'Ice cream sandwich'; Calories = (Get-Random); Fat = 6.0; Carbs = 24; Protein = 4.0}
        @{Dessert = 'Eclair'; Calories = (Get-Random); Fat = 6.0; Carbs = 24; Protein = 4.0}
        @{Dessert = 'Cupcake'; Calories = (Get-Random); Fat = 6.0; Carbs = 24; Protein = 4.0}
        @{Dessert = 'Gingerbread'; Calories = (Get-Random); Fat = 6.0; Carbs = 24; Protein = 4.0}
    ) | Out-UDTableData -Page 0 -TotalCount 5 -Properties $Query.Properties 
}

Alternating Row Colors

You can use a theme to create a table with alternating row colors.

$Theme = @{
    overrides = @{
        MuiTableRow = @{
            root = @{
                '&:nth-of-type(odd)' = @{
                    backgroundColor = "rgba(0,0,0,0.04)"
                }
            }
            head = @{
                backgroundColor = "rgb(255,255,255) !important"
            }
        }
    }
}

New-UDDashboard -Content {
$data = 1..10 | % { [PSCustomObject]@{ Item = $_}}
  New-UDTable -ShowPagination -PageSize 10 -PageSizeOptions @(10, 10) -DisablePageSizeAll -Columns @(
        New-UDTableColumn -Property 'Item' -Title 'Item' -Width 180 -Truncate
    ) -Data $Data -Dense -ShowSearch
} -Theme $Theme