Installation & Activation

Deploying the .sppkg package to the App Catalog and activating the form on a list.

Requirements

• SharePoint Online with the modern list experience. The solution is built on SPFx 1.23 (FormCustomizer extension and ListViewCommandSet).
• Deployment roles: App Catalog administrator (tenant or site collection) for deployment, and site owner for activation on a list. For PowerShell scripts, the PnP.PowerShell module (Install-Module -Name PnP.PowerShell -Scope CurrentUser).
• Building the package: Node.js >=22.14 <23 and dependencies installed in both packages (spfx-form-customizer and spfx-form-customizer-core). A pre-built .sppkg does not require Node.

Building the Package

If you already have a pre-built .sppkg from your vendor, skip directly to Deploying the Package.

1. In both spfx-form-customizer-core and spfx-form-customizer folders, run npm install (the packages do not use workspaces; each has its own node_modules).
2. In the repository root, run npm run ship. The command syncs the core package, runs unit tests, cleans old outputs, and builds the production package.
3. The output is spfx-form-customizer/sharepoint/solution/spfx-form-customizer.sppkg. Scripts and styles are bundled inside the package (includeClientSideAssets) and SharePoint serves them from the App Catalog CDN; no external storage is required.

Deploying the Package

Upload the package to the App Catalog. Choose one of the two options below.

Tenant App Catalog (Recommended)

1. Open the SharePoint Admin Center (https://<tenant>-admin.sharepoint.com), go to Apps and then App Catalog (or directly https://<tenant>.sharepoint.com/sites/appcatalog).
2. Upload spfx-form-customizer.sppkg to the Apps for SharePoint library.
3. In the dialog, check Enable this app and add it to all sites. The package has skipFeatureDeployment: true, so it is deployed tenant-wide without needing to add it to individual sites.
4. Confirm by clicking Enable app.

Site Collection App Catalog

If you do not have access to the tenant App Catalog, a site collection administrator can create a dedicated App Catalog (Add-PnPSiteCollectionAppCatalog) and upload the package there. The solution will then only be available on sites within that site collection.

Activating the Form on a List

Deploying the package alone does not change anything on lists. You must enable the form on a list using one of the methods below. Activation sets the CustomFormCustomizer component (ID 910d1ea6-1bac-43f1-8f31-01aeba0c3605) as the New, Edit, and Display form for the selected content types.

"Custom form" / "Open FormCraft 365 editor" Button (Form Activator)

The package includes the FormActivatorCommandSet extension, which adds a command to the list command bar for managing the custom form (replacing PowerShell) and, when custom list actions are configured, also adds buttons to the command bar and context menu.

1. Open the list and on the command bar click Custom form (if a custom form is not yet active on the list) or Open FormCraft 365 editor (if a custom form is already active). Only site owners see this command (checked via ManageWeb permission, or designer group membership). Visibility and activation status are determined immediately when the command bar loads from page permissions and cached for the browser session (sessionStorage) so the bar does not flicker; actual permissions are always verified when loading and saving the configuration. If the form is already active, the button opens the form designer directly (RibbonBuilderHost), where you can edit the form and manage activation via the List Activation button.
2. In the Custom Form Activation dialog, optionally select another list on the site (lists with template 100, 120, and 1100 are offered; document libraries are not offered).
3. Choose which modes the form should be used for: New item (NewForm), Edit item (EditForm), Display item (DisplayForm).
4. Check the list content types (hidden types and folders are not offered) and click Activate custom form. The dialog also offers two options (enabled by default): Disable offline availability of the list (without this, list buttons and actions may not appear for users with Microsoft Lists sync; the list will not be available offline) and Disable quick edit (grid view) (prevents editing outside the form). FormCraft rules (required fields, locks, calculations) only apply inside the form; edits via Excel, Power Automate, API, or the mobile app will only be constrained if rules are configured directly on SharePoint columns. Failure to update these list settings is only a warning. When deactivating, you can use Restore offline availability and quick edit to revert both settings. For already active types, Update settings and Deactivate (restore default SP form) buttons are available.

PowerShell (Manage-FormCustomizer.ps1)

For bulk management, the repository includes the script scripts/Manage-FormCustomizer.ps1 (supports both PnP.PowerShell 1.x and 2.x). When run, it connects interactively to the site (Connect-PnPOnline -Interactive) or reuses an existing connection to the same URL. It sets the NewFormClientSideComponentId, EditFormClientSideComponentId, and DisplayFormClientSideComponentId properties on the list's content types (excluding folders 0x0120) via Set-PnPContentType, just like the "Custom form" dialog.

# Check status (NATIVE SHAREPOINT / ACTIVE / OTHER COMPONENT for each form)
.\scripts\Manage-FormCustomizer.ps1 -SiteUrl "https://contoso.sharepoint.com/sites/intranet" -ListTitle "Poptavky" -Action Status

# Activate for NewForm, EditForm, and DisplayForm
.\scripts\Manage-FormCustomizer.ps1 -SiteUrl "https://contoso.sharepoint.com/sites/intranet" -ListTitle "Poptavky" -Action Enable

# Revert to native forms (empty GUID)
.\scripts\Manage-FormCustomizer.ps1 -SiteUrl "https://contoso.sharepoint.com/sites/intranet" -ListTitle "Poptavky" -Action Disable

Files in SiteAssets

Form configurations are stored in the Site Assets library of the site containing the list. The designer creates the SiteAssets/FormCustomizer folder on the first save. How this folder is secured is described in Permissions.

Upgrading to a New Version

1. Before building, increment the version in spfx-form-customizer/config/package-solution.json: both solution.version and features[0].version (format major.minor.patch.build, e.g., 1.9.0.0 to 1.9.1.0). Without a higher version, SharePoint will not accept the new package as an upgrade.
2. Build the package by running npm run ship.
3. In the App Catalog, upload the new .sppkg and confirm replacing the existing one. For tenant-wide deployment, confirm Enable app again.
4. After refreshing the page (or clearing the browser cache), the new version is active. Configurations in SiteAssets, the license key, and the script policy remain unchanged during an upgrade.
5. Upgrading the package (uploading a new .sppkg with add to all sites) does not modify or delete existing Tenant Wide Extensions entries; it only adds missing ones. Always verify after upgrading that the list contains exactly the 6 entries from the table and none are disabled (Disabled = Yes); see Checking Tenant Wide Extensions Entries.

Checking Tenant Wide Extensions Entries (Upgrading to 1.28.1 and from Versions Older Than 1.26.0)

Since version 1.28.1, the Command Set extension consists of two separate components: FormActivatorCommandSet (command bar: "Custom form" / "Open FormCraft 365 editor" command and command bar list actions) and FormListActionsContextMenu (item context menu: context menu list actions only). Each is registered for list templates 100, 120, and 1100. This makes 6 entries in total in the Tenant Wide Extensions list in the App Catalog.

During an upgrade, SharePoint adds entries whose names are missing from the list; it does not modify or delete existing entries, so obsolete ones must be deleted manually. Always verify after upgrading that the list contains exactly the 6 entries from the table and that none have Disabled = Yes (SharePoint does not deliver disabled entries at all, so the corresponding command will not run). Missing or disabled entries will cause the "Custom form" / "Open FormCraft 365 editor" button not to appear on the command bar. Obsolete entries will cause duplicate buttons on the command bar and the admin command to appear in the context menu.

Expected entries (Sequence 0, Disabled No, Web Template and Host Properties empty):

Browser procedure:

1. Open the list https://<tenant>.sharepoint.com/sites/<appcatalog>/Lists/TenantWideExtensions/AllItems.aspx (App Catalog, Site Contents, Tenant Wide Extensions).
2. Add the columns Component Id, Location, List Template, and Component Properties to the view and filter by Component Id 4a8b7c12-5d3e-4f9a-8b1c-6e2d9f4a3b5c.
3. Upgrading to 1.28.1 and newer: delete the old context menu entries—those with Location ClientSideExtension.ListViewCommandSet.ContextMenu whose Component Id is 4a8b7c12-5d3e-4f9a-8b1c-6e2d9f4a3b5c (named FormActivatorCommandSet-ContextMenu-<template>). SharePoint added the new FormListActionsContextMenu-<template> entries with Component Id a9998067-8e06-423f-b8a0-3177988f3a42 automatically; if they are missing from the list, create them.
4. Add any missing entries using the New button according to the table above. Verify that no entry has Disabled = Yes.
5. Delete obsolete entries: those whose Location is only ClientSideExtension.ListViewCommandSet (without the .CommandBar / .ContextMenu suffix), command bar entries with empty Component Properties, and any entries not listed in the table. Go by the Location and Component Id columns, not the title.
6. Changes take effect on sites within approximately 20 minutes; afterwards, refresh the page (Ctrl+F5). The "Custom form" / "Open FormCraft 365 editor" command should appear on the command bar only once and never in the context menu.

Alternative: remove the app from the App Catalog including the recycle bin, and upload it again with add to all sites checked. SharePoint will recreate the entries with the correct Component Ids. During that time, forms will be unavailable across all sites; configurations in SiteAssets remain preserved.

The same via PnP PowerShell (first run only the listing; make changes only after reviewing). The default PnP Management Shell app has been retired, so you must specify your own app registered in your Microsoft Entra ID tenant for -ClientId:

Connect-PnPOnline -Url https://<tenant>.sharepoint.com/sites/<appcatalog> -Interactive -ClientId <your-app-id>
$list = "Lists/TenantWideExtensions"
$barId = "4a8b7c12-5d3e-4f9a-8b1c-6e2d9f4a3b5c"   # FormActivatorCommandSet (command bar)
$ctxId = "a9998067-8e06-423f-b8a0-3177988f3a42"   # FormListActionsContextMenu (context menu, since 1.28.1)
$bar = "ClientSideExtension.ListViewCommandSet.CommandBar"; $ctx = "ClientSideExtension.ListViewCommandSet.ContextMenu"
$mine = { Get-PnPListItem -List $list | Where-Object { $_["TenantWideExtensionComponentId"] -in @($barId, $ctxId) } }
# 1) List: ID | Component Id | Location | template | properties
& $mine | ForEach-Object { "{0} | {1} | {2} | {3} | {4}" -f $_.Id, $_["TenantWideExtensionComponentId"], $_["TenantWideExtensionLocation"], $_["TenantWideExtensionListTemplate"], $_["TenantWideExtensionComponentProperties"] }
# 2) Upgrade to 1.28.1+: DELETE old ContextMenu entries with the command bar Component Id (do not edit; new ones are created by SharePoint / step 4)
& $mine | Where-Object { $_["TenantWideExtensionComponentId"] -eq $barId -and $_["TenantWideExtensionLocation"] -eq $ctx } |
  ForEach-Object { Remove-PnPListItem -List $list -Identity $_.Id -Force }
# 3) Delete obsolete entries (Location without suffix, command bar entries without properties)
& $mine | Where-Object { $_["TenantWideExtensionLocation"] -eq "ClientSideExtension.ListViewCommandSet" -or
  ($_["TenantWideExtensionComponentId"] -eq $barId -and -not $_["TenantWideExtensionComponentProperties"]) } |
  ForEach-Object { Remove-PnPListItem -List $list -Identity $_.Id -Force }
# 4) Add missing entries (existing ones are skipped)
$existing = & $mine
foreach ($tpl in "100","120","1100") {
  foreach ($s in @(@{ Cid = $barId; Loc = $bar; Props = '{"surface":"commandBar"}'; Name = "FormActivatorCommandSet-$tpl" },
                   @{ Cid = $ctxId; Loc = $ctx; Props = '{}'; Name = "FormListActionsContextMenu-$tpl" })) {
    if ($existing | Where-Object { $_["TenantWideExtensionComponentId"] -eq $s.Cid -and $_["TenantWideExtensionLocation"] -eq $s.Loc -and "$($_["TenantWideExtensionListTemplate"])" -eq $tpl }) { continue }
    Add-PnPListItem -List $list -Values @{
      Title = $s.Name; TenantWideExtensionComponentId = $s.Cid; TenantWideExtensionLocation = $s.Loc
      TenantWideExtensionListTemplate = $tpl; TenantWideExtensionComponentProperties = $s.Props
      TenantWideExtensionSequence = 0; TenantWideExtensionDisabled = $false } | Out-Null
  }
}

Uninstallation

1. Deactivate the form on every list: use the "Custom form" dialog (Deactivate) or Manage-FormCustomizer.ps1 -Action Disable. The list will revert to SharePoint's default forms.
2. In the App Catalog, remove the package (Remove, or delete the file from the Apps for SharePoint library).
3. Optionally clean up data: delete the SiteAssets/FormCustomizer folder on sites where the form was used, and remove the Storage Entities:

   Remove-PnPStorageEntity -Key SpfxFormCustomizer_License
   Remove-PnPStorageEntity -Key FormCraft365_ScriptsPolicy
   Remove-PnPStorageEntity -Key SpfxFormCustomizer_ScriptPolicy