reearth.popup

The reearth.popup namespace defines the structure and capabilities of popup dialog components within reearth.

Methods

show

The show method displays a popup with custom HTML content at a specified position relative to the extension widget or block. The popup’s appearance, location, and offset can be configured, making it flexible for various UI needs.

Syntax

reearth.popup.show: (
  html: string,
  options?: Options
) => void;

Parameters

html

Type: string

A string of HTML content to be displayed within the popup.

options

Optional

An object with properties to customize the popup’s appearance and placement:

Type:

type Options = {
  width?: number | string;
  height?: number | string;
  position?: PopupPosition;
  offset?: PopupOffset;
};

• width?: number | string;: Specifies the width of the popup.
• height?: number | string;: Specifies the height of the popup.
• position?: PopupPosition;: Specifies the popup’s position relative to a reference point or an element.

Note

For more information on the options included in PopupPosition, please refer to PopupPosition section.

• offset?: PopupOffset: Defines additional spacing or offset for the popup from its positioned location.

Note

For more information on the options included in PopupOffset, please refer to PopupOffset section.

Return Value:

None (void). The method performs its operation without returning a value.

Example

// Example 1. Display a simple notification popup
reearth.popup.show(`
  <h1 style='color:blue;background:white'>
    You have successfully updated your profile.
  </h1>`, {
  // Set the popup width to 300 pixels
  width: 300,
  // Set the popup height to 100 pixels
  height: 100,
  // Position the popup at the bottom-end of the reference element or viewport
  position: "bottom-end",
  // Adjust the popup's position with specific offsets from the main and cross axis.
  offset: 10, // Set a 10px offset from the target
});

// Example 2. Show a popup with custom HTML, width, and offset adjustments on both axes
reearth.popup.show(`
  <p style='color:blue;background:white'>
    Custom Popup Content
  </p>`, {
  width: "300px",
  height: "150px",
  position: "top-start", // Position popup at the top-left of the target
  offset: {
    // Offset object for fine-tuned placement
    mainAxis: 15, // 15px offset along the main axis
    crossAxis: 10, // 10px offset along the cross axis
    alignmentAxis: null, // No alignment adjustment
  },
});

// Example 3. Show a popup with default dimensions and position
reearth.popup.show("<p>Simple Popup</p>");

postMessage

This enables sending messages to the popup iframe. This function is useful for communication in scenarios where a popup needs to get information from the extension script.

Syntax

reearth.popup.postMessage: (message: any) => void;

Parameters

message

Type: any

The message to be sent.

Return Value:

None (void). The method performs its operation without returning a value.

Example

// Example 1. Sending a simple string message from the popup
reearth.popup.postMessage("Popup completed its task");

// Example 2. Send an object with user interaction details
const userData = {
  action: "submit",
  details: { name: "John Doe", email: "john@example.com" },
};

reearth.popup.postMessage(userData);

update

This allows users to modify the appearance and position of the popup iframe. Users can dynamically adjust properties such as the popup’s width, height, position, and offset without needing to recreate the popup.

Syntax

reearth.popup.update: (options: Options) => void;

Parameters

options

An object that contains properties to update the popup’s size, position, and offset.

Type:

type Options = {
  width?: number | string;
  height?: number | string;
  position?: PopupPosition;
  offset?: PopupOffset;
};

• width?: number | string;: Sets the popup’s new width.
• height?: number | string;: Sets the popup’s new height.
• position?: PopupPosition;: Specifies the new popup’s position relative to a reference point or an element.

Note

For more information on the options included in PopupPosition, please refer to PopupPosition section.

• offset?: PopupOffset;: Adjusts the spacing or offset of the popup from its positioned location.

Note

For more information on the options included in PopupOffset, please refer to PopupOffset section.

Return Value:

None (void). The method performs its operation without returning a value.

Example

// Example 1. Update the popup with specific offset adjustments along both axes
reearth.popup.update({
  width: "250px",
  height: "100px",
  position: "bottom", // Place below the target
  offset: {
    // Offset object for detailed adjustments
    mainAxis: 10, // 10px offset from the target on the main axis
    crossAxis: 5, // 5px offset along the cross axis
  },
});

// Example 2. Adjusting the popup's offset to better accommodate new content or UI layout changes
reearth.popup.update({
  offset: { mainAxis: 25, crossAxis: 15 }, // Adjusting both main and cross axis offsets
  // Width, height, and position are not updated; only the offset changes
});

// Example 3. Adjust the popup's height while keeping other properties the same
reearth.popup.update({
  height: 200, // Set height to 200px
});

close

This method provides a simple way to programmatically close a currently active popup. Users can dismiss the popup based on task completion, logical conditions or other user actions.

Syntax

reearth.popup.close: () => void

Parameters

None

Return Value:

None (void). The method performs its operation without returning a value.

Example

// Close the currently open popup
reearth.popup.close();

Events

close

The close event is triggered when the popup in reearth is closed. This event allows you to execute specific actions, such as cleaning up resources, updating the UI, or notifying other components when the popup is no longer visible.

Syntax

reearth.popup.on("close", () => void): void;

Example

reearth.popup.on("close", () => {
  console.log("The Popup was closed.");
});

References

PopupPosition

The PopupPosition type controls where the popup appears relative to the target element. It provides a range of options for positioning the popup above, below, or to the sides of the extension widget or block, with additional options for alignment adjustments (start, center, or end).

type PopupPosition =
  | "top"
  | "top-start"
  | "top-end"
  | "right"
  | "right-start"
  | "right-end"
  | "bottom"
  | "bottom-start"
  | "bottom-end"
  | "left"
  | "left-start"
  | "left-end";

top: Positions the popup directly above the target.

top-start: Aligns the popup at the top left of the target.

top-end: Aligns the popup above the target and positions it to the right side of the target.

right: Aligns the popup directly to the right of the target.

right-start: Aligns the popup to the right of the target and positions it at the top edge of the target.

right-end: Aligns the popup to the bottom of the right side of the target.

bottom: Positions the popup directly below the target.

bottom-start: Aligns the popup below the target, positioned to the left.

bottom-end: Aligns the popup below the target, positioned to the right.

left: Positions the popup directly to the left of the target.

left-start: Aligns the popup to the top of the left side of the target.

left-end: Aligns the popup to the bottom of the left side of the target.

PopupOffset

The PopupOffset type allows users to control the popup’s distance from the extension widget or block. It provides two options: A number that adjusts the offset along the main axis, and an object for more detailed control over different axes, including main, cross, and alignment axes.

type PopupOffset =
  | number
  | {
      mainAxis?: number;
      crossAxis?: number;
      alignmentAxis?: number | null;
    };

Options

Number

• A single number shifts the popup along its main axis, either toward or away from the target.
• Example: 10 shifts the popup 10 pixels along the main axis.

Object

An object providing fine control with the following properties:

mainAxis?: number: Adjusts the popup’s distance from the target along the main axis. Positive values move the popup farther from the target, negative values bring it closer.

crossAxis?: number: Adjusts the popup’s distance along the cross axis, perpendicular to the main axis.Positive values move the popup in one direction, negative values move it in the opposite direction, depending on the orientation.

alignmentAxis?: number | null: The same axis as crossAxis but applies only to aligned placements and inverts the end alignment. When set to a number, it overrides the crossAxis value. A positive number will move the floating element in the direction of the opposite edge to the one that is aligned, while a negative number the reverse.