UI Kit 1

Avatar

A visual representation of a user (subject to their privacy settings). A row of avatars is displayed in an AvatarStack.

Usage notes

You can access the current user's Atlassian account ID with the useProductContext UI hook.

Import statement

1
2
import ForgeUI, { Avatar } from '@forge/ui';

Props

Example

1
2
<Avatar accountId="5a1234bc8d12345e3f1g11hi" />

AvatarStack

A stack of multiple avatars (name and profile picture) for users, subject to their privacy settings.

Import statement

1
2
import ForgeUI, { AvatarStack } from '@forge/ui';

Props

Example

1
2
import ForgeUI, {render, AvatarStack, Avatar} from '@forge/ui';

const App = () => {
    return (
        <AvatarStack>
            <Avatar accountId="5a1234bc8d12345e3f1g11hi"/>
            <Avatar accountId="2a98a42dbc7ab42e12ee360d"/>
            <Avatar accountId="5d8732lq8jg85a0e3f1g90as"/>
            <Avatar accountId="2h98a10dbl5ab93e62hja23z"/>
            <Avatar accountId="7b20f0bc2d05325e3f1g43ty"/>
            <Avatar accountId="2p72s42dbc7ab42e90gf252d"/>
            <Avatar accountId="2l01x78mf4pqw42e84fg40ad"/>
        </AvatarStack>
    );
};

export const run = render (<App/>);

Badge

An inline visual indicator of a numeric value like a score or number of notifications.

Import statement

1
2
import ForgeUI, { Badge } from '@forge/ui';

Props

Example

A badge with a source-lines-of-code diff count.

1
2
<Text>
  <Badge appearance="removed" text="-10" />
  <Badge appearance="added" text="+27" />
  <Badge appearance="primary" text="5K" />
</Text>

Button

A button that triggers an event or action. A row of buttons is displayed in a ButtonSet.

Import statement

1
2
import ForgeUI, { Button } from '@forge/ui';

Props

Example

1
2
<Button
     text="Sign up"
     onClick={async () => {
       await postSignup(data);
     }}
/>

ButtonSet

A layout container for multiple buttons.

Import statement

1
2
import ForgeUI, { ButtonSet } from '@forge/ui';

Props

Example

1
2
<ButtonSet>
  <Button text="Allow" onClick={handleAllow} />
  <Button text="Deny" onClick={handleDeny} />
</ButtonSet>

Checkbox

See CheckboxGroup.

CheckboxGroup

A logical group of Checkbox components.

Usage notes

• This component can only be used within a Form or a MacroConfig component.
• All Checkbox components must be contained within a CheckboxGroup.

Import statement

1
2
import ForgeUI, { CheckboxGroup, Checkbox } from "@forge/ui";

Props

CheckboxGroup

Checkbox

Example

1
2
<CheckboxGroup label="Products" name="products">
  <Checkbox value="jira" label="Jira" />
  <Checkbox value="confluence" label="Confluence" />
</CheckboxGroup>

Selected values are structured in an array. If the user selects “Jira”, it is passed to onSubmit:

1
2
{
  // ...other form data
  product: ["jira"];
}

Code

An entire block of formatted code, highlighted in the body text.

Import statement

1
2
import ForgeUI, { Code } from '@forge/ui';

Props

Supported languages

The code component currently supports the following programming languages:

"abap", "actionscript", "ada", "arduino", "autoit", "c", "c++", "coffeescript", "csharp", "css", "cuda", "d", "dart", "delphi", "elixir", "erlang", "fortran", "foxpro", "go", "graphql", "groovy", "haskell", "haxe", "html", "java", "javascript", "json", "julia", "kotlin", "latex", "livescript", "lua", "mathematica", "matlab", "objective-c", "objective-j", "objectpascal", "ocaml", "octave", "perl", "php", "powershell", "prolog", "puppet", "python", "qml", "r", "racket", "restructuredtext", "ruby", "rust", "sass", "scala", "scheme", "shell", "smalltalk", "sql", "standardml", "swift", "tcl", "tex", "text", "typescript", "vala", "vbnet", "verilog", "vhdl", "xml", "xquery"

Example

1
2
const App = () => {
  const exampleCodeBlock = `  // React Component
    class HelloMessage extends React.Component {
      render() {
        return (
          <div>
            Hello {this.props.name}
          </div>
        );
      }
    }

    ReactDOM.render(
      <HelloMessage name="Taylor" />,
      mountNode
    );
  `;
  return (
    <Code text={exampleCodeBlock} language="javascript" />
  );
};

DateLozenge

An inline component that displays a calendar date.

Import statement

1
2
import ForgeUI, { DateLozenge } from '@forge/ui';

Props

Example

A text component with a nested DateLozenge component.

1
2
<Text>
  <DateLozenge value={new Date('07-29-1988').getTime()} />
</Text>

DatePicker

A form that lets users select a calendar date.

Usage notes

• The value displayed is in the user’s locale (i.e. 'DD-MM-YYYY' for en-NZ).
• Can only be used inside a Form or a MacroConfig component.

Import statement

1
2
import ForgeUI, { DatePicker } from "@forge/ui";

Props

Example

A date picker to book an appointment.

1
2
<DatePicker name="date" label="Appointment Date" description="Appointment must be made 1 day in advance"/>

The submitted form data. The submitted date is always formatted as 'YYYY-MM-DD'.

1
2
{
  //... other form data
  date: "2019-11-01";
}

Form

A form that contains a list of components, a submit button, and a function that handles the submit event.

Usage notes

Can contain any other component, except another Form component.

Import statement

1
2
import ForgeUI, { Form } from "@forge/ui";

Props

Example

1
2
import ForgeUI, {
  render,
  Button,
  Form,
  Fragment,
  TextField,
  CheckboxGroup,
  Checkbox,
  Macro,
  useState,
  Text,
} from "@forge/ui";

const App = () => {
  // useState is a UI kit hook we use to manage the form data in local state
  const [formState, setFormState] = useState(undefined);

  // Handles form submission, which is a good place to call APIs, or to set component state...
  const onSubmit = async (formData) => {
    /**
     * formData:
     * {
     *    username: 'Username',
     *    products: ['jira']
     * }
     */
    setFormState(formData);
  };

  const goBack = () => {};
  const cancel = () => {};

  // The array of additional buttons.
  // These buttons align to the right of the submit button.
  const actionButtons = [
    <Button text="Go back" onClick={goBack} />,
    <Button text="Cancel" onClick={cancel} />,
  ];

  return (
    <Fragment>
      <Form onSubmit={onSubmit} actionButtons={actionButtons}>
        <TextField name="username" label="Username" />
        <CheckboxGroup name="products" label="Products">
          <Checkbox defaultChecked value="jira" label="Jira" />
          <Checkbox value="confluence" label="Confluence" />
        </CheckboxGroup>
      </Form>
      {formState && <Text>{JSON.stringify(formState)}</Text>}
    </Fragment>
  );
};

export const run = render(<Macro app={<App />} />);

FormCondition

Display or hide a group of components based on a form field's value.

Usage notes

Can only be used inside a Form.

Import statement

1
2
import ForgeUI, { FormCondition } from "@forge/ui";

Props

Example

1
2
<CheckboxGroup label="More options" name="JQLOption">
  <Checkbox label="Run a JQL Query" value="true" />
</CheckboxGroup>
<FormCondition when="JQLOption" is={['true']}>
  <TextField label="JQL Query" name="query" />
</FormCondition>

Heading

A piece of text at the top of a page or section.

Import statement

1
2
import ForgeUI, { Heading } from '@forge/ui';

Props

Example

1
2
<Heading size="large">Title</Heading>
<Text>
    Paragraph text goes here.
</Text>

Image

An image.

Import statement

1
2
import ForgeUI, { Image } from '@forge/ui';

Image permissions

If you are using a URL for the image src, make sure that the image URL is added to the app's manifest file to load the image. For more information on how to declare image sources in an application's manifest file, see image permissions documentation.

Example to add an image URL in the manifest

1
2
permissions:
  external:
    images:
      - '<ImageURL>'

Props

Example

1
2
<Image
  src="https://media.giphy.com/media/jUwpNzg9IcyrK/source.gif"
  alt="homer"
/>

InlineDialog

A dialog that displays outside a block of content in a Confluence page.

The ContextMenu:

The InlineDialog:

Example: Dictionary app

Usage notes

• Usually used for small bits of information
• InlineDialog is required for the confluence:contextMenu module

Import statement

1
2
import ForgeUI, { InlineDialog } from '@forge/ui';

Props

Example

1
2
import ForgeUI, { render, Text, ContextMenu, InlineDialog } from '@forge/ui';

const App = () => {
    return (
        <InlineDialog>
            <Text>Hello world!</Text>
        </InlineDialog>
    );
};

export const run = render(
    <ContextMenu>
        <App/>
    </ContextMenu>
);

Link

An inline component that displays a link.

Import statement

1
2
import ForgeUI, { Link } from '@forge/ui';

Props

Example

A text component with a nested link that displays as a button.

1
2
<Text>
  <Link appearance="button" href="https://atlassian.com">
    Go to Atlassian
  </Link>
</Text>

MacroConfig

A form that defines the configuration options of a macro.

Usage notes

• The MacroConfig component should be used only at the root of the macro config function.

• The MacroConfig component only accepts the following components: CheckboxGroup, DatePicker, RadioGroup, Select, TextArea, TextField, and UserPicker.

• Unlike a Form, the MacroConfig component does not have an onSubmit prop. Instead, you retrieve the values with the useConfig hook.

Import statement

1
2
import ForgeUI, { MacroConfig } from "@forge/ui";

Props

Example

An app that displays information about a pet in a macro. The configuration, as defined by the MacroConfig component, enables users to specify the name and age of the pet, with default values Unnamed Pet and 0.

1
2
import ForgeUI, { render, MacroConfig, TextField } from "@forge/ui";

const defaultConfig = {
  name: "Unnamed Pet",
  age: "0"
};

const Config = () => {
  return (
    <MacroConfig>
      <TextField name="name" label="Pet name" defaultValue={defaultConfig.name} />
      <TextField name="age" label="Pet age" defaultValue={defaultConfig.age} />
    </MacroConfig>
  );
};

export const config = render(<Config />);

ModalDialog

A dialog that appears in a layer above the app’s UI and requires user interaction.

Import statement

1
2
import ForgeUI, { ModalDialog } from '@forge/ui';

Props

Example

The example app below shows a ModalDialog when a Button is clicked.

1
2
const App = () => {
  const [isOpen, setOpen] = useState(false);
  return (
    <Fragment>
      <Button text="Show modal" onClick={() => setOpen(true)} />
      {isOpen && (
        <ModalDialog header="My modal dialog" onClose={() => setOpen(false)}>
          <Text>Hello there!</Text>
        </ModalDialog>
      )}
    </Fragment>
  );
};

The example app below demonstrates how to use the Form and ModalDialog components to prompt the user for information.

1
2
const App = () => {
  const [isOpen, setOpen] = useState(false);
  const [size, setSize] = useState("medium");
  return (
    <Fragment>
      <Button
        text={`Your size is ${size}. Click to change.`}
        onClick={() => setOpen(true)}
      />
      {isOpen && (
        <ModalDialog header="My modal dialog" onClose={() => setOpen(false)}>
          <Form
            onSubmit={data => {
              setSize(data.size);
              setOpen(false);
            }}
          >
            <Select label="T-shirt size" name="size">
              <Option label="Small" value="small" />
              <Option label="Medium" value="medium" />
              <Option label="Large" value="large" />
            </Select>
          </Form>
        </ModalDialog>
      )}
    </Fragment>
  );
};

Radio

See RadioGroup.

RadioGroup

A group of Radio buttons.

Usage notes

Can only be used inside a Form or a MacroConfig component.

Import statement

1
2
import ForgeUI, { RadioGroup, Radio } from "@forge/ui";

Props

RadioGroup

Radio

Example

1
2
<RadioGroup name="flavor" label="Pick a flavor" description="Add a flavor to your recipe">
  <Radio defaultChecked label="Strawberry" value="strawberry" />
  <Radio label="Cinnamon" value="cinnamon" />
  <Radio label="Chocolate" value="chocolate" />
</RadioGroup>

In the form data, if the option was selected:

1
2
{
  //... other form values
  flavor: "strawberry";
}

Range

A slider control that allows the user to select from a range of values.

Usage notes

Can only be used inside a Form component.

Import statement

1
2
import ForgeUI, { Range } from "@forge/ui";

Props

Example

A range component offering the ability to select from numbers 1 to 10.

1
2
<Range
    label="Range"
    name="my-range-field"
    min={1}
    max={10}
    step={1}
/>

SectionMessage

A text callout to alert users to important information.

Import statement

1
2
import ForgeUI, { SectionMessage } from '@forge/ui';

Props

Example

1
2
<SectionMessage title="Heading" appearance="info">
  <Text>Some text content</Text>
  <Text>More content</Text>
</SectionMessage>

Select

A field for users to make a single selection or multiple selections from a list of options.

Usage notes

Can only be used inside a Form or a MacroConfig component.

Import statement

1
2
import ForgeUI, { Select, Option } from "@forge/ui";

Props

Select

Option

Example

A select component offering the ability to select a milestone.

1
2
<Select label="With a defaultSelected" name="milestone">
  <Option defaultSelected label="Milestone 1" value="one" />
  <Option label="Milestone 2" value="two" />
  <Option label="Milestone 3" value="three" />
</Select>

If Milestone 1 is selected, the returned form object contains:

1
2
milestone: "one";

If isMulti is true, the form returns an array:

1
2
// nothing selected
{
  milestone: [];
}

// multiple selections
{
  milestone: ["one", "two"];
}

StatusLozenge

A lozenge to show a status.

Import statement

1
2
import ForgeUI, { StatusLozenge } from '@forge/ui';

Props

Example

A text component with text content and a nested StatusLozenge component.

1
2
<Text>
  You have 4 tickets: <StatusLozenge text="In progress" appearance="inprogress" />
</Text>

Tab

Props

Tabs

A visual divider, used to organize content by grouping similar information into tabs on the same page.

Import statement

1
2
import ForgeUI, { Tabs, Tab } from '@forge/ui';

Props

Example

1
2
<Tabs>
    <Tab label="Tab 1">
        <Text>Hello</Text>
    </Tab>
    <Tab label="Tab 2">
        <Text>World!</Text>
    </Tab>
</Tabs>

Table

A table that displays data and other components.

Usage notes

This component can't contain another Table component within itself.

Import statement

1
2
import ForgeUI, { Table, Head, Row, Cell } from '@forge/ui';

Props

Example

1
2
import ForgeUI, { render, Macro, Table, Head, Cell, Text, Row } from '@forge/ui';

const issues = [
  {
    key: 'XEN-1',
    status: 'In Progress',
  },
  {
    key: 'XEN-2',
    status: 'To Do',
  },
];

const App = () => (
  <Table>
    <Head>
      <Cell>
        <Text>Issue Key</Text>
      </Cell>
      <Cell>
        <Text>Status</Text>
      </Cell>
    </Head>
    {issues.map(issue => (
      <Row>
        <Cell>
          <Text>{issue.key}</Text>
        </Cell>
        <Cell>
          <Text>{issue.status}</Text>
        </Cell>
      </Row>
    ))}
  </Table>
);

export const run = render(<Macro app={<App />} />);

Tag

A visual indicator for UI objects, for quick recognition and navigation.

Import statement

1
2
import ForgeUI, { Tag } from '@forge/ui';

Props

Example

1
2
<Tag text="decision" />
<Tag text="spec" color="blue-light" />

TagGroup

A layout container for multiple tags.

Import statement

1
2
import ForgeUI, { Tag, TagGroup } from '@forge/ui';

Props

Example

A simple group of two tag components.

1
2
<TagGroup>
    <Tag text="tag 1" />
    <Tag text="tag 2" />
</TagGroup>

Text

A piece of plain text with basic text formatting options.

It can also include inline components such as Badge, DateLozenge, and StatusLozenge.

Usage notes

The text formatting options are listed here.

Import statement

1
2
import ForgeUI, { Text } from '@forge/ui';

Props

Example

1
2
import ForgeUI, { Text, Strong } from '@forge/ui';

<Text>
  Some <Strong>bold text</Strong>
</Text>

TextArea

A field for users to enter multiple lines of text.

Usage notes

Can only be used inside a Form component.

Import statement

1
2
import ForgeUI, { TextArea } from "@forge/ui";

Props

Example

A text area for a message.

1
2
<TextArea label="Message" name="message" />

The submitted form data.

1
2
{
  //... other form data
  message: "user input";
}

TextField

A field for users to enter a single line of text.

Usage notes

Can only be used inside a Form or a MacroConfig component.

Import statement

1
2
import ForgeUI, { TextField } from "@forge/ui";

Props

Example

A field for entering a name.

1
2
<TextField label="Name" name="name" />

Toggle

A toggle for viewing or switching between enabled or disabled states.

Import statement

1
2
import ForgeUI, { Toggle } from "@forge/ui";

Props

Example

1
2
<Toggle label="Show section" name="isSectionVisible" />

Tooltip

A tooltip that displays when hovering over another component.

Import statement

1
2
import ForgeUI, { Tooltip } from '@forge/ui';

Props

Example

A tooltip wrapping a button component. Hovering over the button will display the tooltip with Hello World.

1
2
<Tooltip text="Hello World">
    <Button
       text="Hover over me"
       onClick={() => console.log("Hello World")}
    />
</Tooltip>

User

A component that represents a user, displaying details such as name and profile picture, subject to the user's privacy settings.

The User component can also be used within a Text component, appearing as a lozenge with the name of the user when used within this context.

Import statement

1
2
import ForgeUI, { User } from '@forge/ui';

Props

Example

Display a user.

1
2
<User accountId="5a1234bc8d12345e3f1g11hi" />

Note, you can access the current user's Atlassian account ID in the app product context.

UserGroup

A stack of multiple users (name and profile picture), subject to their privacy settings.

The UserGroup component can also be used within a Text component, appearing as lozenges with the names of the users when used within this context.

Import statement

1
2
import ForgeUI, { UserGroup } from '@forge/ui';

Props

Example

A simple group of seven users using the UserGroup component.

1
2
import ForgeUI, { render, UserGroup, User } from '@forge/ui';

const App = () => {
    return (
        <UserGroup>
            <User accountId="5a1234bc8d12345e3f1g11hi"/>
            <User accountId="2a98a42dbc7ab42e12ee360d"/>
            <User accountId="5d8732lq8jg85a0e3f1g90as"/>
            <User accountId="2h98a10dbl5ab93e62hja23z"/>
            <User accountId="7b20f0bc2d05325e3f1g43ty"/>
            <User accountId="2p72s42dbc7ab42e90gf252d"/>
            <User accountId="2l01x78mf4pqw42e84fg40ad"/>
        </UserGroup>
    );
};

export const run = render (<App/>);

UserPicker

A dropdown that lists a selectable range of users on the site.

Usage notes

• This component can only be used inside a Form component.
• This component is not supported on workspace-based products such as Bitbucket.

Import statement

1
2
import ForgeUI, { UserPicker } from "@forge/ui";

Props

Example

A field for selecting a user.

1
2
<UserPicker label="User" name="user" />

The returned Form object contains the Atlassian account ID of the selected user.

1
2
user: "1a2345bc6789012d3e45f67";