UI Kit - @forge/react@9 components

UI Kit components on Forge React version 9 help you build the user interface of your Forge app. Each component is described using a declarative markup language, which can be added to your app.

You can use the following components when building Forge apps:

• Badge
• ButtonSet
• Button
• Checkbox and CheckboxGroup
• Code
• DateLozenge
• DatePicker
• Form
• Heading
• Image
• Image permissions
• Inline
• Link
• ModalDialog
• Radio and RadioGroup
• Range
• SectionMessage
• Select
• Stack
• StatusLozenge
• Table
• Tabs
• TagGroup

Badge

To add the Badge component to your app:

1
2
import { Badge } from '@forge/react';

Description

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

Props

Examples

Appearance property

default

The default form of a badge.

1
2
   <Badge appearance="default">23</Badge>

primary

Use a primary badge to help draw attention to new or updated information.

1
2
   <Badge appearance="primary">23</Badge>

important

Use an important badge to call attention to information that needs to stand out. For example, notifications in Confluence.

1
2
   <Badge appearance="important">23</Badge>

added

Use an added appearance to show additions. For example, when characters are added to a line of code in Bitbucket.

1
2
   <Badge appearance="added">23</Badge>

removed

Use a removed appearance to show removals. For example, when characters are removed from a line of code in Bitbucket.

1
2
   <Badge appearance="removed">23</Badge>

Badge within a Text component

Use a Badge component as an inline text within a Text component.

1
2
   <Text>New issues <Badge appearance="primary">23</Badge></Text>

ButtonSet

To add the ButtonSet component to your app:

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

Description

A layout container for multiple buttons.

Props

Example

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

Button

To add the Button component to your app:

1
2
import { Button } from '@forge/react';

Description

A button that triggers an event or action.

Props

Examples

Appearance property

default

Use the default appearance for most buttons.

1
2
import { Button } from '@forge/react';
<Button
  appearance="default"
  onClick={() => {
    // Handle button click
  }}
>
  Default button
</Button>

subtle

Use a subtle button for secondary actions, such as “Cancel".

1
2
import { Button } from '@forge/react';
<Button
  appearance="subtle"
  onClick={() => {
    // Handle button click
  }}
>
  Subtle button
</Button>

link

Similar to a subtle button, a link button can be used for secondary actions.

1
2
import { Button } from '@forge/react';
<Button
  appearance="link"
  onClick={() => {
    // Handle button click
  }}
>
  Link button
</Button>

subtle-link

Similar to a subtle button, but behaves like a link button. Use a subtle-link button to avoid overwhelming the page with blue links.

1
2
import { Button } from '@forge/react';
<Button
  appearance="subtle-link"
  onClick={() => {
    // Handle button click
  }}
>
  Subtle-link button
</Button>

warning

A warning button appears before we request the user to take action, usually in anticipation of a significant change. These are found mostly in confirmation modals.

1
2
import { Button } from '@forge/react';
<Button
  appearance="warning"
  onClick={() => {
    // Handle button click
  }}
>
  Warning button
</Button>

danger

Use a danger button as a final confirmation for a destructive action such as deleting. These are found mostly in confirmation modals.

1
2
import { Button } from '@forge/react';
<Button
  appearance="danger"
  onClick={() => {
    // Handle button click
  }}
>
  Danger button
</Button>

Disabled property

Use the disabled appearance to indicate a button that is not usable. Also set the disabled property to true.

1
2
import { Button } from '@forge/react';
<Button
  appearance="disabled"
  onClick={() => {
    // Handle button click
  }}
  disabled={true}
>
  Default button
</Button>

Icon and icon position properties

Set the icon property to add-circle and the iconPosition property to before, to position the icon before the button's label.

1
2
import { Button } from '@forge/react';
<Button
  appearance="default"
  icon="add-circle"
  iconPosition="before"
  onClick={() => {
    // Handle button click
  }}
>
  Default button
</Button>

Set the icon property to add-circle and the iconPosition property to after, to position the icon after the button's label.

1
2
import { Button } from '@forge/react';
<Button
  appearance="default"
  icon="add-circle"
  iconPosition="after"
  onClick={() => {
    // Handle button click
  }}
>
  Default button
</Button>

Checkbox and CheckboxGroup

To add Checkbox and CheckboxGroup components to your app:

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

Description

A logical group of Checkbox components.

Props

CheckboxGroup

Checkbox

Example

1
2
const App = () => {
  return (
    <CheckboxGroup label="Products" name="products">
      <Checkbox value="jira" label="Jira" />
      <Checkbox
        value="confluence"
        label="Confluence"
        onChange={({ value, isChecked }) => console.log(value, isChecked)}
      />
    </CheckboxGroup>
  );
};

Selected values are sent as an array. If the user selects “Jira”, it is passed to onSubmit of the surrounding Form:

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

Output

Code

To add the Code component to your app:

1
2
import { Code } from '@forge/react';

Description

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

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"

Examples

Code block

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 language="javascript">
      {exampleCodeBlock}
    </Code>
  );
};

Output

Inline code

1
2
const App = () => {
  return (
    <Text>
      To start creating a changeset, run <Code>yarn changeset</Code>. Then
      you'll be prompted to select packages for release.
    </Text>
  );
};

Output

DateLozenge

To add the DateLozenge component to your app:

1
2
import { Text, DateLozenge } from '@forge/react';

Description

An inline component that displays a calendar date.

Props

Example

A text component with a nested DateLozenge component.

1
2
<DateLozenge value={new Date('2023/09/07').getTime()} />

Output

DatePicker

To add a DatePicker component to your app:

1
2
import { DatePicker } from "@forge/react";

Description

A component that lets users select a calendar date. The value is displayed in the date format for the user's locale, such as 'DD-MM-YYYY' for en-NZ.

Props

Example

A date picker to book an appointment.

1
2
const App = () => {
  return (
    <DatePicker
      name="date"
      label="Appointment Date"
      description="Appointment must be made 1 day in advance"
      onChange={(value) => console.log(value)}
    />
  );
};

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

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

Output

Form

To add the Form component to your app:

1
2
import { Form } from "@forge/react";

Description

A form contains a list of components, a submit button, and a function that handles the submit event. You can also add any other component, except another Form component.

Props

Example

1
2
import React, { useState } from "react";
import {
  Button,
  Form,
  TextField,
  CheckboxGroup,
  Checkbox,
  Text,
} from "@forge/react";

const App = () => {
  const [formState, setFormState] = useState(undefined);

  // Handles form submission
  const onSubmit = (formData) => {
    /**
     * formData:
     * {
     *    username: 'Username',
     *    products: ['jira']
     * }
     */
    setFormState(formData);
  };

  return (
    <>
      <Form onSubmit={onSubmit}>
        <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>}
    </>
  );
};

export default App;

Output

Heading

To add the Heading component to your app:

1
2
import { Heading } from '@forge/react';

Description

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

Props

Example

Size property

small

Use small headings for subsections or subsection headings within a larger topic. They are typically used to provide additional organization and hierarchy within the content.

1
2
import { Heading } from '@forge/react';
<Heading size="small">Small heading</Heading>
<Text>
    Default text
</Text>

medium

Use medium headings for main sections or major sub-topics within the document. They help break down the content into manageable sections and provide a clear visual distinction between different topics.

1
2
import { Heading } from '@forge/react';
<Heading size="medium">Medium heading</Heading>
<Text>
Default text
</Text>

large

Use a large heading to render a heading with a larger font size than other headings on the page. This could be used to emphasize the importance of the heading or to make it stand out from the other content on the page.

1
2
import { Heading } from '@forge/react';
<Heading size="large">Large heading</Heading>
<Text>
Default text
</Text>

Image

To add the Image component to your app:

1
2
import { Image } from '@forge/react';

Description

An image component to display images.

Props

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>'

Image size

The image size property is relative to the container. Here's an example with different image size props, to help illustrate how to use the image component in an app.

Accessibility

Text Alternatives (alt text) are an important factor in digital accessibility as they provide an easy way for non-text content (as per WCAG success criterion) to be perceived through various methods including Assistive Technology. Alt text is informative content which conveys the meaning of non-decorative images, and also provides content when images are slow or fail to load.

This helps users who use:

• Screen readers
• Braille display
• Text-to-speech technology

In order to first apply Alt text correctly, we need to determine whether an image conveys any meaning (non-decorative) or whether it is purely for presentation purposes (decorative).

Non-decorative images

Require image descriptions as they convey meaning or add context to the content. In order to write the most appropriate alt text (image description) for an image, keep the following in mind:

• Describe the message the image is conveying, not what the image is. For example, for an image of a clock that points to 2pm, appropriate alt text would be: “Analog clock with a white face and black arms pointing to 2pm”. Inappropriate alt text would be: “clock”
• Keep alt text to no more than ~100 characters. This allows for a streamlined experience for screen reader users.
• Avoid using “image of…” or “picture of…” assistive technology will add this for you when encountering the image element.

Decorative images

Do not require image descriptions because they are purely presentational and part of the overall design.

• Ensure that the decorative images have an EMPTY alt text attribute: alt="".

Example 1: Using a static image

1
2
import React from 'react';
import { Image } from '@forge/react';

export const App = () => (
   <Image
     src="https://examplecat.png"
     alt="black and white cat lying on brown bamboo chair inside room"
   />
);

Output

Example 1: Using a GIF

1
2
import React from 'react';
import { Image } from '@forge/react';

export const App = () => (
    <Image
      src="https://media.giphy.com/media/jUwpNzg9IcyrK/source.gif"
      alt="Example of an animated GIF depicting Homer Simpson retreating into bushes, referencing the popular 'Homer Simpson disappearing' meme"
    />
);

Output

Inline

To add the Inline component to your app:

1
2
import ForgeUI, { Inline } from '@forge/react';

Description

Inline is a primitive component based on the React Native Flexbox layout model. This component provides the ability to lay out its direct children horizontally.

Props

Sure, here's the table sorted alphabetically by the Name column:

Examples

Alignment

To control the alignment of items you can use the alignBlock and alignInline props which control alignment in the vertical and horizontal axis respectively.

Align block

Use to align children vertically.

1
2

import { Inline, Stack, Text, Tag, Button, Image } from '@forge/react';

export const InlineAlignBlock = () => {
 return (
   <Inline space="space.400">
     <Stack space="space.200">
       <Text>Start (Default)</Text>
       <Inline alignBlock="start" space="space.050">
         <Image src="https://examplecat.png" size="small" />
         <Tag color="blue-light">1</Tag>
         <Tag color="purple-light">2</Tag>
         <Tag color="red-light">3</Tag>
       </Inline>
     </Stack>
     <Stack space="space.200">
       <Text>Center</Text>
       <Inline alignBlock="center" space="space.050">
         <Image src="https://examplecat.png" size="small" />
         <Tag color="blue-light">1</Tag>
         <Tag color="purple-light">2</Tag>
         <Tag color="red-light">3</Tag>
       </Inline>
     </Stack>
     <Stack space="space.200">
       <Text>End</Text>
       <Inline alignBlock="end" space="space.050">
         <Image src="https://examplecat.png" size="small" />
         <Tag color="blue-light">1</Tag>
         <Tag color="purple-light">2</Tag>
         <Tag color="red-light">3</Tag>
       </Inline>
     </Stack>
     <Stack space="space.200">
       <Text>Baseline</Text>
       <Inline alignBlock="baseline" space="space.050">
         <Button
           onClick={() => console.log('Add Image button')}
           appearance="primary"
         >
           Add Image
         </Button>
         <Tag color="blue-light">1</Tag>
         <Tag color="purple-light">2</Tag>
         <Tag color="red-light">3</Tag>
       </Inline>
     </Stack>
   </Inline>
 );
};

Align inline

Use to align children horizontally.

1
2
import { Stack, Text, Inline, Tag } from '@forge/react';

export const InlineAlignInline = () => {
  return (
    <Stack space="space.400">
      <Stack space="space.200">
        <Text>Start (default)</Text>
        <Inline space="space.050" alignInline="start">
          <Tag color="blue-light">1</Tag>
          <Tag color="purple-light">2</Tag>
          <Tag color="red-light">3</Tag>
        </Inline>
      </Stack>
      <Stack space="space.200">
        <Text>Center</Text>
        <Inline space="space.050" alignInline="center">
          <Tag color="blue-light">1</Tag>
          <Tag color="purple-light">2</Tag>
          <Tag color="red-light">3</Tag>
        </Inline>
      </Stack>
      <Stack space="space.200">
        <Text>End</Text>
        <Inline space="space.050" alignInline="end">
          <Tag color="blue-light">1</Tag>
          <Tag color="purple-light">2</Tag>
          <Tag color="red-light">3</Tag>
        </Inline>
      </Stack>
    </Stack>
  );
};

Grow

Use to set whether the container should grow to fill the available space.

1
2
import { Inline, Stack, Text, Tag } from '@forge/react';

export const InlineGrow = () => {
  return (
    <Inline grow="fill" space="space.400">
      <Stack space="space.200">
        <Text>Hug</Text>
        <Inline grow="hug" alignInline="start" space="space.050">
          <Tag color="blue-light">1</Tag>
          <Tag color="purple-light">2</Tag>
          <Tag color="red-light">3</Tag>
        </Inline>
      </Stack>
      <Stack space="space.200">
        <Text>Fill</Text>
        <Inline grow="fill" alignInline="start" space="space.050">
          <Tag color="blue-light">1</Tag>
          <Tag color="purple-light">2</Tag>
          <Tag color="red-light">3</Tag>
        </Inline>
      </Stack>
    </Inline>
  );
};

Row space

Use to represent the space between rows when content wraps.

For a different space value between rows use the rowSpace prop.

1
2
import { Stack, Text, Inline, Tag } from '@forge/react';

export const InlineRowSpace = () => {
  // In this example, instead of creating 20 components manually
  // we are initiating an array with 20 elements with their "key"
  // as the value and mapping each one of them to a `Tag` component
  return (
    <Stack space="space.600">
      <Stack space="space.200">
        <Text>With row space</Text>
        <Inline space="space.100" shouldWrap={true} rowSpace={'space.300'}>
          {[...Array(20).keys()].map((i) => (
            <Tag color={tagColor[i % tagColor.length]}>{`${i + 1}`}</Tag>
          ))}
        </Inline>
      </Stack>
      <Stack space="space.200">
        <Text>Without row space (default)</Text>
        <Inline space="space.100" shouldWrap={true}>
          {[...Array(20).keys()].map((i) => (
            <Tag color={tagColor[i % tagColor.length]}>{`${i + 1}`}</Tag>
          ))}
        </Inline>
      </Stack>
    </Stack>
  );
};

Should wrap

Use to set whether children are forced onto one line or will wrap onto multiple lines.

1
2
import { Inline, Tag} from '@forge/react';

export const InlineShouldWrap = () => {
  // In this example, instead of creating 20 components manually
  // we are initiating an array with 20 elements with their "key"
  // as the value and mapping each one of them 
  // to a `Tag` component
  
  return (
    <Inline space="space.050" shouldWrap={true}>
      {[...Array(20).keys()].map((i) => (
        <Tag color={tagColor[i % tagColor.length]}>{`${i + 1}`}</Tag>
      ))}
    </Inline>  );
};

Space

Use to add a gap in between each child.

1
2
import { Stack, Heading, Inline, Tag } from '@forge/react';

export const InlineSpace = () => {
  return (
    <Stack space="space.100">
      <Heading size="small">Space</Heading>
      <Inline space="space.100" alignInline="start">
        <Tag color="grey-light">1</Tag>
        <Tag color="blue-light">2</Tag>
        <Tag color="green-light">3</Tag>
      </Inline>
      <Inline space="space.200" alignInline="start">
        <Tag color="grey-light">1</Tag>
        <Tag color="blue-light">2</Tag>
        <Tag color="green-light">3</Tag>
      </Inline>
    </Stack>
  );
};

Spread

Use to distribute its children along the horizontal axis.

1
2
import { Stack, Text, Inline, Tag } from '@forge/react'

export const InlineSpread = () => {
  return (
    <Stack space="space.400">
      <Stack space="space.200">
        <Text>With space-between</Text>
        <Inline spread="space-between">
          <Tag color="blue-light">1</Tag>
          <Tag color="purple-light">2</Tag>
          <Tag color="red-light">3</Tag>
        </Inline>
      </Stack>
      <Stack space="space.050">
        <Text>Without space-between</Text>
        <Inline>
          <Tag color="blue-light">1</Tag>
          <Tag color="purple-light">2</Tag>
          <Tag color="red-light">3</Tag>
        </Inline>
      </Stack>
    </Stack>
  );
};

Link

To add the Link component to your app:

1
2
import { Link } from '@forge/react';

Description

A component that displays a link.

Props

Example

A link component that will open the https://atlassian.com website in a new tab when clicked.

1
2
<Link href="https://atlassian.com" openNewTab={true}>
  Go to Atlassian
</Link>

Output

ModalDialog

To add the ModalDialog component to your app:

1
2
import { ModalDialog } from "@forge/react";

Description

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

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 onClick={() => setOpen(true)}>Show modal</Button>
      {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 onClick={() => setOpen(true)}>Show modal</Button>
      {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>
  );
};

Output

Radio and RadioGroup

To add Radio and RadioGroup components to your app:

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

Description

A group of Radio buttons.

Props

RadioGroup

Radio

Example

1
2
const App = () => {
  return (
    <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";
}

Output

Range

To add the Range component to your app:

1
2
import { Range } from "@forge/react";

Description

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

Props

Example

A range component that allows to select a number within the range of 1 to 10

1
2
const App = () => {
  return (
    <Range
      label="Range"
      name="my-range-field"
      min={1}
      max={10}
      step={1}
      onChange={(value) => console.log(value)}
    />
  );
};

Output

SectionMessage

To add the SectionMessage component to your app:

1
2
import { SectionMessage } from '@forge/react';

Description

A text callout to alert users to important information.

Props

Examples

Appearance property

By default, all section message come with an icon and an area for content.

Info

An info (information) section message is used to signify a change in state or important information. This is the default appearance for section messages.

1
2
<SectionMessage title="Title" appearance="info">
  <Text>The content of the section message</Text>
</SectionMessage>

Warning

Use a warning section message to help users:

• Avoid errors
• Manage authentication issues
• Take the actions needed to avoid potentially dangerous actions
• Feel certain they're making the decision, for example, in confirmation modals

1
2
<SectionMessage title="Title" appearance="warning">
  <Text>The content of the section message</Text>
</SectionMessage>

Error

Use an error section message to let the user know when:

• Something destructive or critical has happened
• Access has been denied
• There are connectivity issues

1
2
<SectionMessage title="Title" appearance="error">
  <Text> The content of the section message </Text>
</SectionMessage>

Confirmation

Use a confirmation section message to let the user know that an action or event has happened successfully.

1
2
<SectionMessage title="Title" appearance="confirmation">
  <Text>The content of the section message</Text>
</SectionMessage>

Change

Use a change section message to signify an update to the UI or provide information around new features and onboarding.

1
2
<SectionMessage title="Title" appearance="change">
  <Text>The content of the section message</Text>
</SectionMessage>

Select

To add the Select component to your app:

1
2
import { Select } from "@forge/react";

Description

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

Props

Select

Option

Example

A select component offering the ability to select a milestone.

1
2
const App = () => {
  return (
    <Select
      label="With a defaultSelected"
      name="milestone"
      onChange={({ label, value }) => console.log(label, value)}
    >
      <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"];
}

Output

Stack

To add the Stack component to your app:

1
2
import { Stack } from '@forge/react';

Description

Stack is a primitive component based on the React Native Flexbox layout model. This component provides the ability to lay out its direct children vertically.

Props

Examples

Alignment

To control the alignment of items you can use the alignBlock and alignInline props which control alignment in the vertical and horizontal axis respectively.

Align block

Use to align children vertically.

1
2
import { Inline, Stack, Text, Image, Tag } from '@forge/react'

export const StackAlignBlock = () => {
 return (
   <Inline space="space.600">
     <Stack space="space.200">
       <Text>Start (default)</Text>
       <Inline grow="fill" space="space.100">
         <Image src="https://examplecat.png" size="small" />
         <Stack alignBlock="start" alignInline="start" space="space.100">
           <Tag>1,000 views</Tag>
           <Tag color="green-light">5 votes</Tag>
         </Stack>
       </Inline>
     </Stack>
     <Stack space="space.200">
       <Text>Center</Text>
       <Inline grow="fill" space="space.100">
         <Image src="https://examplecat.png" size="small" />
         <Stack alignBlock="center" alignInline="start" space="space.100">
           <Tag>1,000 views</Tag>
           <Tag color="green-light">5 votes</Tag>
         </Stack>
       </Inline>
     </Stack>
     <Stack space="space.200">
       <Text>End</Text>
       <Inline grow="fill" space="space.100">
         <Image src="https://examplecat.png" size="small" />
         <Stack alignBlock="end" alignInline="start" space="space.100">
           <Tag>1,000 views</Tag>
           <Tag color="green-light">5 votes</Tag>
         </Stack>
       </Inline>
     </Stack>
   </Inline>
 );
};

Align inline

Use to align children horizontally.

1
2
import { Stack, Text, Inline, Tag, Image } from '@forge/react';

export const StackAlignInline = () => {
  return (
    <Inline space="space.600">
      <Stack space="space.100" alignInline="start">
        <Text>Start (default)</Text>
        <Image src="https://examplecat.png" size="small" />
        <Tag>1,000 views</Tag>
        <Tag color="green-light">5 votes</Tag>
      </Stack>
      <Stack space="space.100" alignInline="center">
        <Text>Center</Text>
        <Image src="https://examplecat.png" size="small" />
        <Tag>1,000 views</Tag>
        <Tag color="green-light">5 votes</Tag>
      </Stack>
      <Stack space="space.100" alignInline="end">
        <Text>End</Text>
        <Image src="https://examplecat.png" size="small" />
        <Tag>1,000 views</Tag>
        <Tag color="green-light">5 votes</Tag>
      </Stack>
    </Inline>
  );
};

Grow

Use to set whether the container should grow to fill the available space.

1
2
import { Inline, Stack, Text, Tag }

export const StackGrow = () => {
  return (
    <Inline grow="fill" space="space.500">
      <Stack space="space.200">
        <Text>Hug</Text>
        <Stack grow="hug" space="space.050">
          <Tag color="blue-light">1</Tag>
          <Tag color="purple-light">2</Tag>
          <Tag color="red-light">3</Tag>
        </Stack>
      </Stack>
      <Stack space="space.200">
        <Text>Fill</Text>
        <Stack grow="fill" alignInline="start" space="space.050">
          <Tag color="blue-light">1</Tag>
          <Tag color="purple-light">2</Tag>
          <Tag color="red-light">3</Tag>
        </Stack>
      </Stack>
    </Inline>
  );
}; 

Space

Use to add a gap in between each child.

1
2
import { Stack, Inline, Tag } from '@forge/react';

export const StackSpace = () => {
  return (
    <Inline space="space.400">
      <Stack space="space.100" alignInline="start">
        <Tag color="blue-light">1</Tag>
        <Tag color="purple-light">2</Tag>
        <Tag color="red-light">3</Tag>
      </Stack>
      <Stack space="space.200" alignInline="start">
        <Tag color="blue-light">1</Tag>
        <Tag color="purple-light">2</Tag>
        <Tag color="red-light">3</Tag>
      </Stack>
    </Inline>
  );
};

Spread

Use to distribute its children along the vertical axis.

1
2
import { Inline, Stack, Text, Tag, Image } from '@forge/react'

export const StackAlignBlock = () => {
  return (
    <Inline space="space.600">
      <Stack space="space.200">
        <Text>With space-between</Text>
        <Inline grow="fill" space="space.100">
          <Image src="https://examplecat.png" size="medium" />
          <Stack
            alignBlock="start"
            alignInline="start"
            space="space.050"
            spread="space-between"
          >
            <Tag color="blue-light">1</Tag>
            <Tag color="purple-light">2</Tag>
            <Tag color="red-light">3</Tag>
          </Stack>
        </Inline>
      </Stack>
      <Stack space="space.200">
        <Text>Without space-between</Text>
        <Inline grow="fill" space="space.100">
          <Image src="https://examplecat.png" size="medium" />
          <Stack alignBlock="center" alignInline="start" space="space.050">
            <Tag color="blue-light">1</Tag>
            <Tag color="purple-light">2</Tag>
            <Tag color="red-light">3</Tag>
          </Stack>
        </Inline>
      </Stack>
    </Inline>
  );
};

StatusLozenge

To add the StatusLozenge component to your app:

1
2
import { StatusLozenge } from '@forge/react';

Description

A lozenge to show a status.

Props

Example

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

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

Output

Table

To add the Table component to your app:

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

Description

A table that displays data and other components.

Props

Example

1
2
import { Table, Head, Cell, Text, Row } from '@forge/react';
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>
);

Output

Tabs

To add the Tabs component to your app:

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

Description

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

Props

Example

1
2
<Tabs>
    <Tab label="Tab 1">
        <Text>Hello world!</Text>
    </Tab>
    <Tab label="Tab 2">
        <Text>The quick brown fox jumps over the lazy dog</Text>
    </Tab>
</Tabs>

Output

TagGroup

To add the TagGroup component to your app:

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

Description

A layout container for multiple tags.

Props

Example

1
2
<TagGroup>
  <Tag>tag 1</Tag>
  <Tag>tag 2</Tag>
</TagGroup>

Output

Tag

To add the Tag component to your app:

1
2
import { Tag } from '@forge/react';

Description

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

Props

Example

Color property

Customize the color of the Tag component based on your specific needs and preferences, allowing for clear visual distinctions and effective communication within your application.

1
2
      <Tag color="grey-light">Comment</Tag>
      <Tag color="grey">Note</Tag>
      <Tag color="blue">Info</Tag>
      <Tag color="blue-light">Specification</Tag>
      <Tag color="green">Decision</Tag>
      <Tag color="green-light">Success</Tag>
      <Tag color="purple">Progress</Tag>
      <Tag color="purple-light">Feature</Tag>
      <Tag color="red">Important</Tag>
      <Tag color="red-light">Error</Tag>
      <Tag color="teal">Task</Tag>
      <Tag color="teal-light">Review</Tag>
      <Tag color="yellow">Warning</Tag>
      <Tag color="yellow-light">Reminder</Tag>

TextArea

To add the TextArea component to your app:

1
2
import { TextArea } from "@forge/react";

Description

A field for users to enter multiple lines of text.

Props

Example

A text area for a message.

1
2
const App = () => {
  const [inputValue, setInputValue] = useState("");

  return (
    <TextArea
      label="Message"
      name="message"
      value={inputValue}
      onChange={(value) => setInputValue(value)}
    />
  );
};

Output

TextField

To add the TextField component to your app:

1
2
import { TextField } from "@forge/react";

Description

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

Props

Example

A field for entering a name.

1
2
const App = () => {
  const [inputValue, setInputValue] = useState("");

  return (
    <TextField
      label="Name"
      name="name"
      value={inputValue}
      onChange={(value) => setInputValue(value)}
    />
  );
};

Output

Text

To add the Text component to your app:

1
2
import { Text } from '@forge/react';

Description

A piece of plain text with basic text formatting options.

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

Props

Example

1
2
import { Text, Code, Strike, Em, Strong} from '@forge/react';
<Text>
  Here <Code>is<Code/> <Strike>some</Strike><Em>example</Em><Strong>text.</Strong>
</Text>

Output

Toggle

To add the Toggle component to your app:

1
2
import { Toggle } from "@forge/react";

Description

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

Props

Example

1
2
const App = () => {
  return (
    <Toggle
      label="Show section"
      name="isSectionVisible"
      onChange={(value) => console.log(value)}
    />
  );
};

Output

Tooltip

To add the Tooltip component to your app:

1
2
import { Tooltip } from '@forge/react';

Description

A tooltip that displays when hovering over another component.

Props

Example

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

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

Output

UserGroup

To add the UserGroup component to your app:

1
2
import { UserGroup } from '@forge/react';

Description

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.

Props

Examples

Display a user group

A simple group of seven users using the UserGroup component.

1
2
import { UserGroup, User } from '@forge/react';
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>
    );
};

Output

Display as an inline user group within a Text component

1
2
<Text>
  Contributors: <UserGroup>
        <User accountId="5a1234bc8d12345e3f1g11hi" />
        <User accountId="3a1236bc8d12345e3f1g11ok" />
        <User accountId="3g123an8t12345a3c1h11ris" />
    </UserGroup>
</Text>

Output

UserPicker

To add the UserPicker component to your app:

1
2
import { UserPicker } from "@forge/react";

Description

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

This component is not supported on workspace-based products such as Bitbucket.

Props

1
2
(user: {
  id: string;
  type: string;
  avatarUrl: string;
  name: string;
  email: string;
}) => void

Example

A field for selecting a user.

1
2
const App = () => {
  return (
    <UserPicker
      label="User"
      name="user"
      onChange={(user) => console.log(user)}
    />
  );
};

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

1
2
user: "1a2345bc6789012d3e45f67";

Output

User

To add the User component to your app:

1
2
import { User } from '@forge/react';

Description

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.

Props

Examples

Display a user

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

Output

Display as an inline user within a Text component

1
2
<Text>
  Contributors: <User accountId="5a1234bc8d12345e3f1g11hi" /> <User accountId="3a1264bc8d12346eky1g11ok" />
</Text>

Output