App elements are generally controls that your app can "register" at runtime. These elements are within Deskpro itself and once registered, they can send events to your app when triggered. The current list of app elements types is as follows:

• menu - adds a menu of links to the app header

• home_button - adds "Home" button to the app header

• edit_button - adds "Edit" button to the app header

• refresh_button - adds "Refresh" button to the app header

• plus_button - adds the "Plus" button call to action to the app header

• cta_external_link - adds an external link to the app header, optionally showing alongside the app icon

Registering Elements

Each of these element types may be registered from the app client when using the apps SDK. Some examples of registering and deregistering elements is as follows:

import { useDeskproAppClient } from "@deskpro/app-sdk";
import { useEffect } from "react";

export const MyComponent = () => {
  const { client } = useDeskproAppClient();

  useEffect(() => {

    // Register a "home" button
    client?.registerElement("myHomeButton", {
      type: "home_button"
    });

    // Register a "refresh" button
    client?.registerElement("myRefreshButton", {
      type: "refresh_button"
    });

    // Register a "plus button" button
    client?.registerElement("myPlusButton", {
      type: "plus_button"
    });
    
    // Register a "menu" with two options
    client?.registerElement("myMenu", {
      type: "menu",
      items: [{
        title: "Do Something",
        payload: "something",
      }, {
        title: "Do Something Else",
        payload: "something_else",
      }],
    });
		
    // Register an "external CTA link" button
    client?.registerElement("myExternalCtaLink", {
      type: "cta_external_link",
      url: "https://example.com/",
      hasIcon: true,
    });

  }, [client]);

  return (
    <>
    </>
  );
};
 copy

After registering each of these elements, your app target will ook something like this:

Listening to Element Events

When an element is triggered, usually by clicking on it, your app will receive an event. To listen to this event, add a listener for it using the useDeskproAppEvents() hook.

useDeskproAppEvents({
  onElementEvent(id: string, type: string, payload?: AppElementPayload) {
    console.log(id, type, payload);
  },
});
 copy

A more practical example would use a switch() statement to do something when a particlar element is triggered. In this case, let's do something when the "home_button" is clicked:

useDeskproAppEvents({
  onElementEvent(id: string, type: string, payload?: AppElementPayload) {
    switch (id) {
      case "myHomeButton":
        // do something when the home button is clicked
        break;
    }
  },
});
 copy

Note: you can also pass an arbitrary payload with each element. This is useful for when you want to pass aditional parameters with each event, e.g. an ID for something

Deregistering Elements

As well as registering elements, you may deregister them (remove) them too. To do this, use the deregisterElement() method of the SDK client:

useEffect(() => {

  // Remove the "home" button
  client?.deregisterElement("myHomeButton");

}, [client]);
 copy