showFlag

The showFlag bridge method enables UI Kit and Custom UI apps to open flags in the Atlassian app's flag group.

Function signature

1
2
function showFlag(flagOptions: FlagOptions): {
  close: () => Promise<boolean | void>;
};

interface FlagOptions {
  id: string;
  title?: string;
  description?: string;
  type?: "info" | "success" | "warning" | "error";
  appearance?: "info" | "success" | "warning" | "error";
  actions?: FlagAction[];
  isAutoDismiss?: boolean;
}

interface FlagAction {
  text: string;
  onClick: () => void;
}

Arguments

• flagOptions
  • id: A unique string identifier for the flag. This property is required.
  • title: The bold text shown at the top of the flag.
  • description: The secondary content shown below the flag's title.
  • type: The type of the flag. This will determine the flag's icon.
  • appearance: Makes the flag appearance bold if provided. Bold appearance flags don't have a dismiss button, so they require more direct user interaction.
  • actions: The list of clickable actions to be shown at the bottom of the flag. You can incorporate the router object's navigate method within these actions to direct users to a different page in the same tab.
  • isAutoDismiss: Whether the flag is auto-dismissable or not. If set to true, the flag will automatically close after 8 seconds.

Returns

• A flag object that contains a close function.

Flag appearance types

Normal flags:

• Include a dismiss button with a close icon
• Can be auto-dismissed after 8 seconds
• Suitable for informational messages

Bold appearance flags:

• Does not include a dismiss button with a close icon but can be closed through action buttons
• Can still be closed programmatically or through auto-dismiss
• Actions are optional but recommended for better user experience
• Typically used for prominent notifications or important information

Examples

1
2
import { showFlag } from "@forge/bridge";
showFlag({
  id: "info-normal",
  title: "Information",
  type: "info",
  description: "This is an informational message.",
  isAutoDismiss: true,
});

1
2
import { showFlag } from "@forge/bridge";
showFlag({
  id: "info-bold",
  title: "No team members found",
  type: "info",
  appearance: "info", // Bold appearance, no dismiss button with a close icon
  description: "Add teammates to get started.",
  actions: [
    {
      text: "Add teammates",
      onClick: () => console.log("Navigate to team page"),
    },
    {
      text: "Skip",
      onClick: () => console.log("User skipped"),
    },
  ],
});

See Jira Project Stats App for showFlag used in an app.