import Global from '../../_global.mdx';

# spo customaction add

Adds a user custom action for site or site collection

## Usage

```sh
m365 spo customaction add [options]
```

## Options

```md definition-list
`-u, --webUrl <webUrl>`
: Url of the site or site collection to add the custom action

`-n, --name <name>`
: The name of the custom action

`-t, --title <title>`
: The title of the custom action

`-l, --location <location>`
: The actual location where this custom action need to be added like `CommandUI.Ribbon`

`-g, --group [group]`
: The group where this custom action needs to be added like `SiteActions`

`-d, --description [description]`
: The description of the custom action

`--sequence [sequence]`
: Sequence of this CustomAction being injected. Use when you have a specific sequence with which to have multiple CustomActions being added to the page

`--actionUrl [actionUrl]`
: The URL, URI or JavaScript function associated with the action. URL example `~site/_layouts/sampleurl.aspx` or `~sitecollection/_layouts/sampleurl.aspx`

`--imageUrl [imageUrl]`
: The URL of the image associated with the custom action

`-e, --commandUIExtension [commandUIExtension]`
: XML fragment that determines user interface properties of the custom action

`--registrationId [registrationId]`
: Specifies the identifier of the list or item content type that this action is associated with, or the file type or programmatic identifier

`--registrationType [registrationType]`
: Specifies the type of object associated with the custom action. Allowed values `None`, `List`, `ContentType`, `ProgId`, `FileType`. Default `None`

`--rights [rights]`
: A case sensitive string array that contain the permissions needed for the custom action. Allowed values `EmptyMask`, `ViewListItems`, `AddListItems`, `EditListItems`, `DeleteListItems`, `ApproveItems`, `OpenItems`, `ViewVersions`, `DeleteVersions`, `CancelCheckout`, `ManagePersonalViews`, `ManageLists`, `ViewFormPages`, `AnonymousSearchAccessList`, `Open`, `ViewPages`, `AddAndCustomizePages`, `ApplyThemeAndBorder`, `ApplyStyleSheets`, `ViewUsageData`, `CreateSSCSite`, `ManageSubwebs`, `CreateGroups`, `ManagePermissions`, `BrowseDirectories`, `BrowseUserInfo`, `AddDelPrivateWebParts`, `UpdatePersonalWebParts`, `ManageWeb`, `AnonymousSearchAccessWebLists`, `UseClientIntegration`, `UseRemoteAPIs`, `ManageAlerts`, `CreateAlerts`, `EditMyUserInfo`, `EnumeratePermissions`, `FullMask`. Default `EmptyMask`

`-s, --scope [scope]`
: Scope of the custom action. Allowed values `Site`, `Web`. Default `Web`

`--scriptBlock [scriptBlock]`
: Specifies a block of script to be executed. This attribute is only applicable when the Location attribute is set to ScriptLink

`--scriptSrc [scriptSrc]`
: Specifies a file that contains script to be executed. This attribute is only applicable when the Location attribute is set to ScriptLink

`-c, --clientSideComponentId [clientSideComponentId]`
: The Client Side Component Id (GUID) of the custom action

`-p, --clientSideComponentProperties [clientSideComponentProperties]`
: The Client Side Component Properties of the custom action. Specify values as a JSON string : `'{"testMessage":"Test message"}'`
```

<Global />

## Remarks

Running this command from the Windows Command Shell (cmd.exe) or PowerShell for Windows OS XP, 7, 8, 8.1 without bash installed might require additional formatting for command options that have JSON, XML or JavaScript values because the command shell treats quotes differently. For example, this is how ApplicationCustomizer user custom action can be created from the Windows cmd.exe:

```sh
m365 spo customaction add --webUrl https://contoso.sharepoint.com/sites/test --title "YourAppCustomizer" --name "YourName" --location "ClientSideExtension.ApplicationCustomizer" --clientSideComponentId b41916e7-e69d-467f-b37f-ff8ecf8f99f2 --clientSideComponentProperties '{\"testMessage\":\"Test message\"}'
```

Note, how the clientSideComponentProperties option (-p) has escaped double quotes `'{\"testMessage\":\"Test message\"}'` compared to execution from bash `'{"testMessage":"Test message"}'`.

The `--rights` option accepts **case sensitive** values.

:::warning[Escaping JSON in PowerShell]

When using the `--clientSideComponentProperties` option it's possible to enter a JSON string. In PowerShell 5 to 7.2 [specific escaping rules](./../../../user-guide/using-cli.mdx#escaping-double-quotes-in-powershell) apply due to an issue. Remember that you can also use [file tokens](./../../../user-guide/using-cli.mdx#passing-complex-content-into-cli-options) instead.

:::

## Examples

Adds a tenant-wide SharePoint Framework Application Customizer extension in the specified site.

```sh
m365 spo customaction add --webUrl https://contoso.sharepoint.com/sites/test --title "YourAppCustomizer" --name "YourName" --location "ClientSideExtension.ApplicationCustomizer" --clientSideComponentId b41916e7-e69d-467f-b37f-ff8ecf8f99f2 --clientSideComponentProperties '{"testMessage":"Test message"}'
```

Adds a tenant-wide SharePoint Framework **modern List View** Command Set extension in the specified site.

```sh
m365 spo customaction add --webUrl https://contoso.sharepoint.com/sites/test --title "YourCommandSet" --name "YourName" --location "ClientSideExtension.ListViewCommandSet" --clientSideComponentId db3e6e35-363c-42b9-a254-ca661e437848 --clientSideComponentProperties '{"sampleTextOne":"One item is selected in the list.", "sampleTextTwo":"This command is always visible."}' --registrationId 100 --registrationType List
```

Creates a url custom action in the SiteActions menu in the specified site.

```sh
m365 spo customaction add --webUrl https://contoso.sharepoint.com/sites/test --title "YourTitle" --name "YourName" --location "Microsoft.SharePoint.StandardMenu" --group "SiteActions" --actionUrl "~site/SitePages/Home.aspx" --sequence 100
```

Creates a custom action in the **classic** Document Library edit context menu on the specified site.

```sh
m365 spo customaction add --webUrl https://contoso.sharepoint.com/sites/test --title "YourTitle" --name "YourName" --location "EditControlBlock" --actionUrl "javascript:(function(){ return console.log('CLI for Microsoft 365 rocks!'); })();" --registrationId 101 --registrationType List
```

Creates a ScriptLink custom action with script source in **classic pages** in the specified site collection.

```sh
m365 spo customaction add --webUrl https://contoso.sharepoint.com/sites/test --title "YourTitle" --name "YourName" --location "ScriptLink" --scriptSrc "~sitecollection/SiteAssets/YourScript.js" --sequence 101 --scope Site
```

Creates a ScriptLink custom action with script block in **classic pages** in the specified site.

```sh
m365 spo customaction add --webUrl https://contoso.sharepoint.com/sites/test --title "YourTitle" --name "YourName" --location "ScriptLink" --scriptBlock "(function(){ return console.log('Hello CLI for Microsoft 365!'); })();" --sequence 102
```

Creates a **classic List View** custom action located in the Ribbon in the specified site.

```sh
m365 spo customaction add --webUrl https://contoso.sharepoint.com/sites/test --title "YourTitle" --name "YourName" --location "CommandUI.Ribbon" --commandUIExtension '<CommandUIExtension><CommandUIDefinitions><CommandUIDefinition Location="Ribbon.List.Share.Controls._children"><Button Id="Ribbon.List.Share.GetItemsCountButton" Alt="Get list items count" Sequence="11" Command="Invoke_GetItemsCountButtonRequest" LabelText="Get Items Count" TemplateAlias="o1" Image32by32="_layouts/15/images/placeholder32x32.png" Image16by16="_layouts/15/images/placeholder16x16.png" /></CommandUIDefinition></CommandUIDefinitions><CommandUIHandlers><CommandUIHandler Command="Invoke_GetItemsCountButtonRequest" CommandAction="javascript: alert(ctx.TotalListItems);" EnabledScript="javascript: function checkEnable() { return (true);} checkEnable();"/></CommandUIHandlers></CommandUIExtension>'
```

Creates a custom action with delegated rights in the SiteActions menu in the specified site.

```sh
m365 spo customaction add --webUrl https://contoso.sharepoint.com/sites/test --title "YourTitle" --name "YourName" --location "Microsoft.SharePoint.StandardMenu" --group "SiteActions" --actionUrl "~site/SitePages/Home.aspx" --rights "AddListItems,DeleteListItems,ManageLists"
```

## Response

The command won't return a response on success.

## More information

- UserCustomAction REST API resources: [https://msdn.microsoft.com/en-us/library/office/dn531432.aspx#bk_UserCustomAction](https://msdn.microsoft.com/en-us/library/office/dn531432.aspx#bk_UserCustomAction)
- UserCustomAction Locations and Group IDs: [https://msdn.microsoft.com/en-us/library/office/bb802730.aspx](https://msdn.microsoft.com/en-us/library/office/bb802730.aspx)
- UserCustomAction Element: [https://msdn.microsoft.com/en-us/library/office/ms460194.aspx](https://msdn.microsoft.com/en-us/library/office/ms460194.aspx)
- UserCustomAction Rights: [https://msdn.microsoft.com/en-us/library/office/microsoft.sharepoint.spbasepermissions.aspx](https://msdn.microsoft.com/en-us/library/office/microsoft.sharepoint.spbasepermissions.aspx)
