UI Kit 2 components
UI Kit 2 hooks
Product bridge APIs
Jira bridge APIs
Upgrade to latest UI Kit 2
Previous versions

This page is about the previous version of UI Kit. The latest version of UI Kit is now in Preview.

We highly recommend upgrading to and utilizing the latest version. Get started with UI Kit's latest library of components to quickly build your user interface.

UI Kit 2 (preview) components

UI Kit 2 (preview) components 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

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

NameTypeRequiredDescription
appearancestringThe appearance of the badge. Valid values are default, primary, important, added, and removed. Defaults to default.

Examples

Appearance property

default

The default form of a badge.

Example image of a rendered default badge

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

primary

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

Example image of a rendered primary badge

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.

Example image of a rendered important badge

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.

Example image of a rendered added badge

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.

Example image of a rendered removed badge

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>

Example image of a rendered added badge within a text component

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

NameTypeRequiredDescription
childrenArray<Button>YesThe buttons to display in the set. On large-width devices, the buttons are rendered in a row that wraps to fit. On mobile devices, the buttons are full-width.

Example

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

Screenshot of what the rendered button set should look like

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

NameTypeRequiredDescription
onClick() => void | Promise<void>Handler to be called on click.
childrenstringYesThe button's label text.
appearancestringThe appearance of the button. Valid values are:
  • default
  • subtle
  • link
  • subtle-link
  • warning
  • danger

  • Default value is default.
    disabledbooleanWhether the user interaction is disabled. Defaults to false.
    iconstringAn icon to display with the button's text. Valid values are icons from @atlaskit/icon. For example, "add-circle" or "graph-line".
    iconPositionstringWhere to render the icon relative to the text. Valid values are: "before" | "after". Defaults to "before".

    Examples

    Appearance property

    default

    Use the default appearance for most buttons.

    Example image of rendered button

    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".

    Example image of rendered button

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



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

    Example image of rendered button

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



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

    Example image of rendered button

    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.

    Example image of rendered button

    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.

    Example image of rendered button

    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.

    Example image of rendered button

    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.

    Example image of rendered button

    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.

    Example image of rendered button

    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

    NameTypeRequiredDescription
    childrenArray<Checkbox>YesAn array of checkbox components in this group.
    labelstringYesThe label text that describes the checkbox group.
    namestringYesThe name of the property when submitted.
    descriptionstringThe text description of the checkbox group.

    Checkbox

    NameTypeRequiredDescription
    defaultCheckedbooleanWhether the checkbox is initially checked. Defaults to false
    isRequiredboolean Indicates to the user whether or not a Checkbox must be selected to submit the form. If a field is required, an asterisk appears at the end of that field’s label.
    labelstringYesThe label text.
    valuestringYesThe value of the property when submitted. Empty if not selected.
    onChange({ value: string, isChecked: boolean }) => void | PromiseNoAn event handler that can be asynchronous. Allows you to read values from the component without having to submit as part of a Form.

    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

    Example image of rendered checkbox group

    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

    NameTypeRequiredDescription
    childrenstringYesThe code to be formatted.
    languagestringThe language in which the code is written. Refer to Supported languages for a list of valid values.

    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

    Example image of rendered code

    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

    Example image of rendered inline code

    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.

    You can only use this component as a child element with Text as the parent component.

    Props

    NameTypeRequiredDescription
    valuenumberYesThe date represented as the number of milliseconds elapsed since Unix epoch.

    Example

    A text component with a nested DateLozenge component.

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

    Output

    Example image of rendered date

    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

    NameTypeRequiredDescription
    defaultValuestringThe initial date value to display. It should be formatted as 'YYYY-MM-DD'.
    isRequiredbooleanIndicates to the user whether or not a value is required in this field to submit the form. If a field is required, an asterisk appears at the end of that field’s label.
    labelstringYesThe label to display.
    namestringYesThe key to which the input value is assigned in the returned form object.
    descriptionstringThe text description of the date picker.
    placeholderstringThe placeholder helper text.
    onChange(value: string) => void | PromiseNoAn event handler that can be asynchronous. Allows you to read values from the component without having to submit as part of a Form.

    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

    Example image of rendered date picker

    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

    NameTypeRequiredDescription
    childrenArray<ForgeComponent>YesAny component, except for a Form. Form components are controlled automatically and have their values added to the onSubmit call.
    onSubmit(formData: Record<string, any>) => void;YesHandler to be called on form submission. The argument, formData, is a list of key-value pairs. The keys are the input element names specified for the form’s user interface components such as username (see Example section).
    submitButtonTextstringThe label text displayed on the form’s submit button. Defaults to Submit.
    actionButtonsArray<Button>An array of Button components. These buttons align to the right of the Submit button, letting you define additional form behaviors.

    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

    Example image of rendered form

    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

    NameTypeRequiredDescription
    childrenstringYesThe text of the heading.
    size'small' | 'medium' | 'large'The size of the heading. Defaults to medium.

    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.

    Example image of rendered small heading

    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.

    Example image of rendered medium heading

    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.

    Example image of rendered large heading

    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

    NameTypeRequiredDescription
    altstringYesThe alternative text displayed if the image is not loaded.
    srcstringYesThe URL of the image.
    size'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'The size of the image. Defaults to xlarge.

    Image permissions

    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:
          - 'https://www.example-dev.com/image.png'
    

    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.

    Examples of different image sizes that include xsmall, small, medium, large, xlarge to optimize images for different devices

    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

    black and white cat sitting on a bamboo chair, smirking as if to say, "This room is my fluffy kingdom"

    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

    Example of an animated GIF depicting Homer Simpson retreating into bushes, referencing the popular 'Homer Simpson disappearing' meme

    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:

    NameTypeRequiredDescription
    alignBlockstringNoAligns children vertically. Valid values are:
    • start
    • center
    • end
    • baseline
    • stretch

    Defaults to start.
    alignInlinestringNoAligns children horizontally. Valid values are:
    • start
    • center
    • end

    Defaults to start.
    growstringNoSets whether the container should grow to fill the available space. Valid values are:
    • hug to use space only as required by its children
    • fillto take all space provided by the parent element.

    Defaults to hug.
    rowSpacestringNoRepresents the space between rows when content wraps. Used to override the space value in between rows. Valid values are Space tokens:
  • space.0
  • space.025
  • space.050
  • space.075
  • space.100
  • space.150
  • space.200
  • space.250
  • space.300
  • space.400
  • space.500
  • space.600
  • space.800
  • space.1000
  • shouldWrapbooleanNoSets whether children are forced onto one line or will wrap onto multiple lines.
    Defaults to false.
    spacestringNoRepresents the space between each child. Valid values are Space tokens:
  • space.0
  • space.025
  • space.050
  • space.075
  • space.100
  • space.150
  • space.200
  • space.250
  • space.300
  • space.400
  • space.500
  • space.600
  • space.800
  • space.1000
  • spreadstringNoDistributes its children along the horizontal axis. Overrides the alignInline property. Valid value is:
  • space-between
  • 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.

    Rendered tags using the alignBlock property with an inline component. The tags are displayed vertically, with equal spacing between them.

    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.

    Rendered tags using the alignInline property with an inline component. The tags are displayed horizontally, with equal spacing between them.

    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.

    Rendered tag components with adjustable growth behavior using the grow property

    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.

    Rendered tags with and without row spacing for wrapping content

    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.

    Rendered tags with adjustable wrapping behavior.

    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.

    Rendered tags with adjustable spacing with space tokens set to space.100 and space.200 in this example

    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.

    Rendered tag components distributed horizontally using the spread property.

    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>
      );
    };
    

    To add the Link component to your app:

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

    Description

    A component that displays a link.

    Props

    NameTypeRequiredDescription
    hrefstringYes

    The prop href behaves like an HTML href. You should include http(s):// for full URLs. Relative paths, such as /wiki, are also supported.

    childrenstringYesThe text to display for the link.
    openNewTabbooleanWhether or not the link should open in a new tab. Defaults to false.

    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

    Example image of rendered link

    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

    NameTypeRequiredDescription
    childrenArray<ForgeComponent>YesThe content of the modal dialog.
    headerstringYesThe title of the modal dialog.
    onClose() => void | Promise<void>YesThe function that is called when the modal is closed.
    appearance"danger" | "warning"Shows an icon next to the header and changes the appearance of the action button. If appearance is not specified, the default appearance is a primary button with no header icon.
    closeButtonTextstringThe label text displayed on the modal's close button. Defaults to Cancel.
    width"small" | "medium" | "large" | "x-large"The width of the modal dialog. This can range from a small popup to almost full-screen width. Defaults to "medium".

    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

    Example image of rendered modal dialog

    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

    NameTypeRequiredDescription
    isRequiredboolean Indicates to the user whether or not a radio button is required to submit the form. If a field is required, an asterisk appears at the end of that field’s label. Defaults to false
    labelstringYesThe label text to display.
    namestringYesThe key to which the selected radio button is assigned in the returned form object.
    descriptionstringThe text description of the radio group.
    childrenArray<Radio>YesThe radio buttons in the group. Each Radio button is defined by a label that sets the radio button's text and return a value unique within the group if the radio button is selected. One can have a defaultChecked property set to true to be the selected on initial load.
    onChange(value: string) => void | PromiseNoAn event handler that can be asynchronous. Allows you to read values from the component without having to submit as part of a Form.

    Radio

    NameTypeRequiredDescription
    defaultCheckedbooleanWhether this radio button is initially selected. Defaults to false
    labelstringYesThe label text to display.
    valuestringYesThe value of the property when submitted. Empty if not selected.

    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

    Example image of rendered radio group

    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

    NameTypeRequiredDescription
    labelstringYesThe label text to display.
    namestringYesThe key to which the input value is assigned in the returned form object.
    defaultValuestringThe selected range value that’s initially displayed.
    minstringThe minimum value for the slider's range.
    maxstringThe maximum value for the slider's range.
    stepstringThe stepping interval between the min and max values that the slider can snap to. Must be greater than 0.
    onChange(value: number) => void | PromiseNoAn event handler that can be asynchronous. Allows you to read values from the component without having to submit as part of a Form.

    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

    Example image of rendered range

    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

    NameTypeRequiredDescription
    childrenArray<Text>YesThe content of the section message.
    titlestringThe title of the section message.
    appearance"info" | "warning" | "error" | "confirmation" | "change"Shows an icon next to the title and changes the appearance of the section message. If appearance is not specified, the default appearance is "info".

    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.

    Example image of rendered section info message

    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

    Example image of rendered section warning message

    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

    Example image of rendered section error message

    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.

    Example image of rendered section confirmation message

    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.

    Example image of rendered section change message

    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

    NameTypeRequiredDescription
    childrenArray<Option>YesThe select list items. Each Option is defined by a label, which is displayed in the list, and a value, which is the string returned if the item is selected. Each Option can also have a defaultSelected prop, to make it selected on initial load.
    isMultibooleanWhether the user can select multiple items from the list. Defaults to false
    isRequiredboolean Indicates to the user whether or not at least one item from the dropdown list must be selected to submit the form. If a field is required, an asterisk appears at the end of that field’s label.
    labelstringYesThe label text to display.
    namestringYesThe key the user-submitted value is assigned to in the returned form object. If isMulti is true, the submitted value is an array of strings; otherwise, it is a string.
    descriptionstringThe text description of the select field.
    placeholderstringThe placeholder text to display when no options are selected. It defaults to “Select …”
    onChange({ label: string, value: any } | { label: string, value: any }[]) => void | PromiseNoAn event handler that can be asynchronous. Allows you to read values from the component without having to submit as part of a Form.

    Option

    NameTypeRequiredDescription
    defaultSelectedbooleanWhether this option is initially selected. Defaults to false
    labelstringYesThe label text to display.
    valuestringYesIf selected and submitted it will be included in the value of the array property.

    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

    Example image of rendered select

    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

    NameTypeRequiredDescription
    alignBlockstringNoAligns children vertically. Valid values are:
    • start
    • center
    • end

    Defaults to start.
    alignInlinestringNoAligns children horizontally. Valid values are:
    • start
    • center
    • end

    Defaults to undefined which equates to stretch.
    growstringNoSets whether the container should grow to fill the available space. Valid values are:
    • hug to use space only as required by its children
    • fillto take all space provided by the parent element.

    Defaults to hug.
    spacestringNoRepresents the space between each child. Valid values are Space tokens:
  • space.0
  • space.025
  • space.050
  • space.075
  • space.100
  • space.150
  • space.200
  • space.250
  • space.300
  • space.400
  • space.500
  • space.600
  • space.800
  • space.1000
  • spreadstringNoDistributes its children along the vertical axis. Overrides the alignBlock property. Valid value is:
  • space-between
  • 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.

    Rendered tags using the alignBlock property with a stack component. The tags are displayed vertically, with equal spacing between them.

    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.

    Rendered tags using the alignInline property with an inline component. The tags are displayed horizontally, with equal spacing between them.

    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.

    Rendered tag components with adjustable growth behavior using the grow property

    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.

    Rendered tags with adjustable spacing with space tokens set to space.400 and space.200 in this example

    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.

    Rendered tag components distributed horizontally using the spread property.

    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.

    You can only use this component as a child element with Text as the parent component.

    Props

    NameTypeRequiredDescription
    childrenstringYesThe text content of the status lozenge.
    appearancestringThe appearance of the status lozenge. Valid values are default, inprogress, moved, new, removed, and success. Defaults to default.

    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

    Example image of rendered status lozenge

    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

    NameTypeRequiredDescription
    TableHead | Array<Row>YesTop-level component of a table.
    HeadArray<Cell>YesContainer of cells for the heading row of the table. A table can only contain one Head.
    RowArray<Cell>YesContainer of cells for a row of the table.
    rowsPerPagenumberNoMaximum number of rows shown in the table before pagination is automatically enabled. Defaults to 25. Set to 0 to disable automatic pagination.
    CellForgeComponentYesCell can contain any value or component, except a Table component.

    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

    Example image of rendered table

    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

    NameTypeRequiredDescription
    childrenTabYesThe tab components to be displayed.
    labelstringYesThe label text to display.
    childrenForgeComponentYesThe contents to display in the tab.

    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

    Example image of rendered tabs

    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

    NameTypeRequiredDescription
    childrenArray<Tag>YesThe tag components to be displayed. See Tag for further details on the props.

    Example

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

    Output

    Example image of rendered tag group

    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

    NameTypeRequiredDescription
    childrenstringYesThe text content to display.
    colorstringThe color of the tag. Valid values are grey-light, grey, blue, blue-light, green, green-light, purple, purple-light, red, red-light, teal, teal-light, yellow, yellow-light.

    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.

    The examples of tags in the provided image are intended solely as recommendations.

    Example image of rendered tag

    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

    NameTypeRequiredDescription
    defaultValuestringThe initial text value of the field.
    valuestringThe value of the text area field. Allows you to read and control the value when used outside a Form component.
    onChange(value: string) => void | PromiseNoAn event handler that can be asynchronous. Allows you to read values from the component without having to submit as part of a Form.
    isMonospacedbooleanWhether or not to style the text as monospaced.
    isRequiredbooleanIndicates to the user whether or not a value is required in this field to submit the form. If a field is required, an asterisk appears at the end of that field’s label.
    labelstringYesThe label text to display.
    namestringYesThe key to which the input value is assigned in the returned form object.
    descriptionstringThe text description of the text area input.
    placeholderstringThe placeholder helper text.
    spellCheckbooleanWhether to check the text in this form element for spelling errors.. Defaults to false

    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

    Example image of rendered text area

    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

    NameTypeRequiredDescription
    labelstringYesThe label text to display.
    namestringYesThe key to which the input value is assigned in the returned form object.
    defaultValuestringThe initial text value of the field.
    valuestringThe value of the text field. Allows you to read and control the value when used outside a Form component.
    onChange(value: string) => void | PromiseNoAn event handler that can be asynchronous. Allows you to read values from the component without having to submit as part of a Form.
    isRequiredbooleanIndicates to the user whether or not a value is required in this field to submit the form. If a field is required, an asterisk appears at the end of that field’s label.
    descriptionstringThe text description of the field.
    placeholderstringThe placeholder helper text.
    type"text" | "number" | "email" | "tel" | "password"The input type of the field.
    autoComplete"off"Optionally disable HTML autocomplete.

    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

    Example image of rendered text-field

    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

    NameTypeRequiredDescription
    childrenstring | ForgeInlineComponentYesThe text and inline components to display.
    code<Code>code</Code>code
    em <Em>em</Em>

    em

    link

    <Link href="https://www.atlassian.com" />

    <Link href="https://www.atlassian.com">Atlassian</Link>

    See the Link documentation for more details.

    www.atlassian.com

    Atlassian

    strike <Strike>strike</Strike> strike
    strong <Strong>strong</Strong>

    strong

    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

    Example image of rendered text component

    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

    NameTypeRequiredDescription
    labelstringYesThe label text to display.
    namestringYesThe key the input value is assigned to in the form object returned.
    defaultCheckedbooleanWhether the toggle is initially checked. Defaults to false
    onChange(value: boolean) => void | PromiseNoAn event handler that can be asynchronous. Allows you to read values from the component without having to submit as part of a Form.

    Example

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

    Output

    Example image of rendered toggle

    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

    NameTypeRequiredDescription
    childrenForgeElementYesThe component to wrap the tooltip around.
    textstringYesThe message to display in the tooltip.

    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

    Example image of rendered tooltip

    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

    NameTypeRequiredDescription
    childrenArray<User>YesThe users (specified by Atlassian account ID) whose avatars and/or names are displayed in the UserGroup. See User for further details on the 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

    Example image of a rendered group of seven Atlassian users

    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

    Example image of a rendered inline group of three Atlassian users within a Text component

    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

    NameTypeRequiredDescription
    isMultibooleanWhether the user can select multiple users from the list. Defaults to false
    isRequiredbooleanIndicates to the user whether or not a value is required in this field to submit the form. If a field is required, an asterisk appears at the end of that field’s label..
    labelstringYesThe label text to display.
    namestringYesThe key to which the input value is assigned in the returned form object. If isMulti is true, the submitted value is an array of strings; otherwise, it is a string.
    defaultValuestringThe initial user to display. The value should be an Atlassian account ID.
    descriptionstringThe text description of the user picker field.
    placeholderstringThe placeholder helper text.
    onChange
    1
    2
    (user: {
      id: string;
      type: string;
      avatarUrl: string;
      name: string;
      email: string;
    }) => void
    
    NoAn event handler that can be asynchronous. Allows you to read values from the component without having to submit as part of a Form.

    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

    Example image of rendered User picker

    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

    NameTypeRequiredDescription
    accountIdstringYesThe Atlassian account ID of the user.

    Examples

    Display a user

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

    You can access the current user's Atlassian account ID in the app product context.

    Output

    Example image of rendered pictures and names of Atlassian users

    Display as an inline user within a Text component

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

    Output

    Example image of a rendered picture and name of an Atlassian user within a Text component

    Rate this page: