Add a surface to extension UI

The extension UI boilerplate code includes an extension details page surface, which users will access under Extensions > [your extension’s details page] > Configuration in the Netlify UI. You can change this to a different surface or add additional ones for various locations in the Netlify UI.

This document covers how to update your extension UI to add an additional surface to render in the Netlify UI. It also includes a list of available surfaces and their configuration values for your reference.

For more information about all of the components and surfaces available, refer to the extension UI reference docs.

Add a new surface

First, edit the extension’s configuration file (extension.yaml) to add a new surface under surfaces.

For example, to add the Site Notifications Configuration surface, add extension-site-notifications-configuration.
extension.yaml
```
config:
  ui:
    surfaces:
      - extension-team-configuration
      - extension-site-notifications-configuration
```
This signals to the Netlify UI that it should show your extension UI when a user installs your extension and navigates to Site configuration > Notifications.

Next, create the new component that Netlify should render for this surface in the Netlify UI. For example, add new file called SiteNotificationsConfiguration.tsx under src/ui/surfaces/ with the following component code:

 import {
   Card,
   CardTitle,
   Form,
   FormField,
   FormFieldSecret,
   SiteNotificationsConfigurationSurface,
 } from "@netlify/sdk/ui/react/components";

 export const SiteNotificationsConfiguration = () => {
   const onSubmit = (values) => {
     // Do something with form values
   };

   return (
     <SiteNotificationsConfigurationSurface>
       <Card>
         <Form onSubmit={onSubmit}>
           <FormField name="username" label="Username" />
           <FormFieldSecret name="password" label="password" />

           <Select
             name="notification_provider"
             label="Notification Provider"
             options={[
               { label: "SMS", value: "SMS" },
               { label: "Email", value: "email" },
               { label: "Carrier Pigeon", value: "carrier_pigeon" },
             ]}
           />
         </Form>
       </Card>
     </SiteNotificationsConfigurationSurface>
   );
 };

Next, update the extension UI application to render your new component when a user navigates to the correct surface:

import { Surfaces } from "@netlify/sdk/ui/react";
import { SurfaceRouter, SurfaceRoute } from "@netlify/sdk/ui/react/components";
import { TeamConfiguration } from "./surfaces/TeamConfiguration.jsx";
import { SiteNotificationsConfiguration } from "./surfaces/SiteNotificationsConfiguration.jsx";

export const App = () => (
  <SurfaceRouter>
     <SurfaceRoute surface={Surfaces.TeamConfiguration}>
       <TeamConfiguration />
     <SurfaceRoute>

     <SurfaceRoute surface={Surfaces.SiteNotificationsConfiguration}>
       <SiteNotificationsConfiguration />
     <SurfaceRoute>
  </SurfaceRouter>
);

Next, redeploy the extension so that you can preview it locally. Redeploying and updating your private extension is only required when you add or remove surfaces.
Now, you can run start local development. Once the server starts, navigate to Site configuration > Notifications for your site in the Netlify UI and the new surface should appear. The original boilerplate surface should also still appear when you navigate to Team settings > General team settings

Available surfaces

The Netlify SDK supports extension UI for the following surfaces across team sections and site sections of the Netlify UI.

Team sections

For team features and configurations, you can add the following surfaces:

Extension details page

Note that this surface is sometimes referred to as the Team Configuration surface.

Location in the Netlify UI: Extensions > [your extension’s details page] > Configuration
Component name: TeamConfigurationSurface
Value for extension.yaml: extension-team-configuration

Netlify Connect settings

Location in the Netlify UI:
- Connect > Add a new data layer > Add data sources
- Connect > Data layer settings > Data sources > Add a data source.
Component name: ConnectConfigurationSurface
Value for extension.yaml: extension-connect-configuration

Note that this surface should reflect the configuration options you specify for your connector. Learn more about specifying configuration options for a connector.

Site sections

For site features and configurations, you can add the following surfaces:

General site settings

Location in the Netlify UI: Site configuration > General
Component name: SiteGeneralConfigurationSurface
Value for extension.yaml: extension-site-general-configuration

Site access & security settings

Location in the Netlify UI: Site configuration > Access & security
Component name: SiteAccessConfigurationSurface
Value for extension.yaml: extension-site-access-configuration

Site build & deploy settings

Location in the Netlify UI: Site configuration > Build & deploy
Component name: SiteBuildDeployConfigurationSurface
Value for extension.yaml: extension-site-build-and-deploy-configuration

Site notification settings

Location in the Netlify UI: Site configuration > Notifications
Component name: SiteNotificationsConfigurationSurface
Value for extension.yaml: extension-site-notifications-configuration

Site visual editor settings

Location in the Netlify UI: Site configuration > Visual editor > Content sources > Add a content source
Component name: VisualEditorConfigurationSurface
Value for extension.yaml: extension-visual-editor-configuration