Share

Examples
Typescript ❤️

Fabric Share Element

Install
yarn add @atlaskit/share
npm
@atlaskit/share
Source
Bitbucket
Bundle
unpkg.com
Changelog
Latest

6.1.0

Minor Changes

Patch Changes

  • Updated dependencies

Note: This component is designed for internal Atlassian development.

External contributors will be able to use this component but will not be able to submit issues.

Note: This component is currently in developer preview.

Please experiment with and test this package, but be aware that the API may change at any time. Use at your own risk, preferably not in production.

This package provides the view components allowing users to share a resource by sharing with User Picker, or by copying the share link.

The goal is to provide a consistent share experience across products.

Usage

Import the component in your React app as follows:

import ShareDialogContainer from '@atlaskit/share;

Example

Share Component

Options

Recipient controls
Product (groups are not enabled in Jira)
confluence
Is Browse Users Disabled(if true, only emails can be selected)
Share config (controls whether emails are available)
Email sharing allowed
Features controls
Enable Integration Tabs
Enable Additional Tabs
Enable Integration Split Button
Enable Integration Menu Button
Is Public Link
Is Copy Disabled
Custom UI components
Custom Share Dialog Trigger Button
Custom Share Dialog Title
Custom Share Form Helper Message
Custom Trigger Button Tooltip Text
Custom Trigger Button Icon
Show Restriction Message
Custom Footer
Share Fields Footer
URL shortening
Use URL shortener
Use URL shortener legacy API
Auto open dialog
Core behavioural settings
Enable Smart User Picker
Dialog Placement
bottom-start
Close Share Dialog on escape key press
Trigger Button Style
icon-only
Trigger Button Appearance
default
Trigger Button Tooltip Position
top
Locale
en-US

Share Props

onTriggerButtonClick function

Callback function to be called on trigger button click.

() => undefined

onDialogOpen function

Callback function to be called on dialog open.

() => undefined

onDialogClose function

Callback function to be called on dialog close.

() => undefined

isAutoOpenDialog boolean

Allow the share dialog to be opened via a Prop.

shareClient object

Share service client implementation that gets share configs and performs share. Optional, a default one is provided.

share required function
content,
recipients,
metadata,
comment
=> Promise
shareRequestId string required
getConfig function required cloudId => Promise
disableSharingToEmails boolean

urlShortenerClient object

URL Shortener service client implementation that may shorten links for copy. Optional, a default one is provided.

shorten function required data => Promise
shortUrl string required

shortLinkData object

Data provided to the urlShortenerClient to shorten the shared URL. If it is not provided, the link will not be shortened. If link shortening fails, the full URL will be shared instead.

cloudId string
product string required
type string required
params required Recordstring, string
originId string

cloudId string required

Cloud ID of the instance. Note: we assume this props is stable.

orgId string

Organisation ID of the instance.

dialogPlacement import

Placement of the modal to the trigger button.

@atlaskit/popper.Placement

dialogZIndex number

Z-index that the popup should be displayed in. This is passed to the portal component. Defaults to layers.modal() from @atlaskit/theme.

loadUserOptions import

Function used to load users options asynchronously. Not needed if smart user picker is enabled.

@atlaskit/smart-user-picker.LoadOptions

originTracingFactory function required

Factory function to generate new Origin Tracing instance.

=>
id string required
addToUrl required link => string
toAnalyticsAttributes required attrs => One of
originIdGenerated string required
originProduct string required
,
originId string required
originProduct string required

productId union required

Product ID (Canonical ID) in ARI of the share request. Note: we assume this props is stable.

One of
"bitbucket",
"confluence",
"jira-addon",
"jira-core",
"jira-platform",
"jira-polaris",
"jira-portfolio",
"jira-servicedesk",
"jira-software",
"jira-unknown",
"trello"

renderCustomTriggerButton function

Render function for a custom Share Dialog Trigger Button.

function
args,
triggerProps
=> React.ReactNode

shareAri string required

Atlassian Resource Identifier of a Site resource to be shared.

shareContentType string required

Content Type of the resource to be shared. It will also affect on the successful share message in the flag. A pre-defined list as follows: blogpost board calendar draft filter issue media page project pullrequest question report repository request roadmap site space Any other unlisted type will have a default message of "Link shared".

shareContentSubType string

Content SubType of the resource to be shared. Optional. embed

shareContentId string

Content ID of the resource to be shared. Optional.

shareTitle string required

Title of the resource to be shared that will be sent in notifications.

shareFormTitle React.ReactNode

Title of the share modal.

React.ReactNode

shareFormHelperMessage string

Copy for helper message to be displayed under share form input box. If set to empty string, no helper message will be displayed

shouldCloseOnEscapePress boolean

To enable closing the modal on escape key press.

showFlags function required

Callback function for showing successful share flag(s) with a parameter providing details of the flag, including the type of the message with a localized default title This package has an opinion on showing flag(s) upon successful share, and Flag system is NOT provided. Instead, showFlag prop is available for this purpose.

flags => undefined

enableSmartUserPicker boolean = false

Power the user picker with smarts. To enable smart user picker, the following props are used:

  • product: 'jira' or 'confluence'
  • loggedInAccountId: if not provided, defaults to obtaining from request context
  • cloudId

loggedInAccountId string

The userId of the sharer. If not provided, smart user picker defaults it to the value 'Context' which will tell the recommendation service to extract the value from the request context.

triggerButtonAppearance import

Appearance of the share modal trigger button

undefined.IconButtonProps['appearance']

triggerButtonIcon React.ComponentType<import>

Share button Icon

React.ComponentType@atlaskit/icon.IconProps

triggerButtonStyle union

Style of the share modal trigger button.

One of
"icon-only",
"icon-with-text",
"text-only"

triggerButtonTooltipPosition union

Position of the tooltip on share modal trigger button.

One of
"top",
"right",
"bottom",
"left",
"mouse"

triggerButtonTooltipText React.ReactNode

Custom text of the tooltip on share modal trigger button.

React.ReactNode

bottomMessage React.ReactNode

Message to be appended to the modal.

React.ReactNode

useUrlShortener boolean deprecated

Use the shortLinkData prop instead. *

  • Whether we should use the Atlassian Url Shortener or not.
  • Note that all products may not be supported.

shareeAction union = "view"

Action that will be performed by the recipient when he/she receives the notification.

One of
"view",
"edit"

product union = "confluence"

Optional, this prop can be jira or confluence. Default value is confluence. We use this prop to control different text messages in UI.

One of
"jira",
"confluence"

productAttributes import

attributes that apply to the product

undefined.Props['productAttributes']

customHeader React.ReactNode

Header for the share dialog.

React.ReactNode

customFooter React.ReactNode

Footer for the share dialog.

React.ReactNode

userPickerOptions intersection

common Props to pass to userPicker

Pick@atlaskit/smart-user-picker.Props, One of
"onFocus",
"header",
"includeNonLicensedUsers"
&
noOptionsMessageHandler union One of
value => One of
string,
null,
React.ReactNode
,
null
getPlaceholderMessage function
allowEmail,
isBrowseUsersDisabled
=> react-intl-next.MessageDescriptor
getLabelMessage function
allowEmail,
isBrowseUsersDisabled
=> react-intl-next.MessageDescriptor
getRequiredMessage function
allowEmail,
isBrowseUsersDisabled
=> react-intl-next.MessageDescriptor

onUserSelectionChange function

Callback function to be called on user selection change in the share form.

value => undefined

shareFieldsFooter React.ReactNode

Footer component to display under the share form fields.

React.ReactNode

isCopyDisabled boolean

Indicates if the copy link and share link are disabled

integrationMode union

Indicates the mode for integrations to be displayed

One of
"tabs",
"split",
"menu",
"off"

isMenuItemSelected boolean

Indicates if the menu item was clicked when 'integrationMode=menu' is active

shareIntegrations Array<object>

List of share integrations

Array
type string required
Icon required React.ComponentType
Content required React.ComponentType
onClose required () => undefined
changeTab index => undefined

additionalTabs Array<object>

List of additional tabs to be displayed

Array
label string required
Content required React.ComponentType
onClose required () => undefined
changeTab index => undefined

builtInTabContentWidth number

Content container width used by built-in tabs

tabIndex number

Optionally sets a tabIndex value if you need to set focus

copyTooltipText string

If present, will add a tooltip to the copy link and display link tooltip text

isBrowseUsersDisabled boolean

disable looking up users and teams

workspaceAri string

Atlassian resource identifier of the workspace initiating the share

isSubmitShareDisabled boolean

Indicates if share submit button is disabled

Notes

The share modal will be instantiated immediately but starts hidden. It will retain the form state until the user either:

  • triggers a share = share completed
  • presses Esc = share cancelled

A click outside the modal will hide it, but the form state will be retained (as long as the share is not cancelled).