Share Dialog

The Share dialog gives people the ability to publish an individual story to their timeline, a friend's timeline, a group, or in a private message on Messenger. This does not require Facebook Login or any extended permissions, so it is the easiest way to enable sharing on the web.

If people are in a browser that is not logged in with a cookie, the drop-down list for choosing the audience for your share doesn't appear. This is also true if the app uses the feed dialog instead of the share dialog or if the app uses iframe web view.

To implement the Share Dialog in native mobile apps read our guides for iOS and Android.

Integration

The Share dialog is available in the Facebook SDK for JavaScript. You can use the following code snippet to trigger the Share dialog. You can also use a redirect to a URL. For details, see Advanced Topics.

Facebook SDK for JavaScript

Trigger a Share Dialog using the FB.ui function with the share method parameter to share a link.

To share a link:

FB.ui({
  method: 'share',
  href: 'https://developers.facebook.com/docs/',
}, function(response){});

Try it yourself!

Include open graph meta tags on the page at this URL to customize the story that is shared back to Facebook.

Note that response.error_message will appear only if someone using your app has authenciated your app with Facebook Login.

Parameters

Common Parameters

The JS SDK will provide these parameters automatically.

Parameter Description

Parameter	Description
`app_id`	Your app's unique identifier. Required.
`redirect_uri`	The URL to redirect to after a person clicks a button on the dialog. Required when using URL redirection.
`display`	Determines how the dialog is rendered. If you are using the URL redirect dialog implementation, then this will be a full page display, shown within Facebook.com. This display type is called `page`. If you are using one of our iOS or Android SDKs to invoke the dialog, this is automatically specified and chooses an appropriate display type for the device. If you are using the Facebook SDK for JavaScript, this will default to a modal `iframe` type for people logged into your app or `async` when using within a game on Facebook.com, and a `popup` window for everyone else. You can also force the `popup` type when when you use the Facebook SDK for JavaScript, if necessary. Mobile web apps will always default to the `touch` display type.

app_id

Your app's unique identifier. Required.

redirect_uri

The URL to redirect to after a person clicks a button on the dialog. Required when using URL redirection.

display

Determines how the dialog is rendered.

If you are using the URL redirect dialog implementation, then this will be a full page display, shown within Facebook.com. This display type is called page.
If you are using one of our iOS or Android SDKs to invoke the dialog, this is automatically specified and chooses an appropriate display type for the device.
If you are using the Facebook SDK for JavaScript, this will default to a modal iframe type for people logged into your app or async when using within a game on Facebook.com, and a popup window for everyone else. You can also force the popup type when when you use the Facebook SDK for JavaScript, if necessary.
Mobile web apps will always default to the touch display type.

`share` Parameters

Parameter	Description	Default
`href`	The link attached to this post. Required when using method `share`. Include open graph meta tags in the page at this URL to customize the story that is shared.	Current URL
`hashtag`	A hashtag specified by the developer to be added to the shared content. People will still have the opportunity to remove this hashtag in the dialog. The hashtag should include the hash symbol, e.g. `#facebook`.	`null`
`quote`	A quote to be shared along with the link, either highlighted by the user or predefined by the developer, as in a pull quote on an article.	`null`
`mobile_iframe`	If set to `true` the share button will open the share dialog in an iframe on top of your website (For more information see Mobile Web Share Dialog. This option is only available for mobile, not desktop.	`false`

Response Data

Parameter	Description
`post_id`	Only available if the user is logged into your app using Facebook and has granted `publish_actions`. If present, this is the ID of the published Open Graph story.
`error_message`	Only available if the user is logged into your app using Facebook Login.

Advanced Topics

You can also take advantage of the following advanced features.

The mobile web share dialog also has the ability to be show in an iFrame on top of your content. If a person finishes the sharing flow, the dialog will dismiss and leave them back to the original piece of content so they can easily continue consuming it.

Code Example

To enable the mobile web share dialog in an iframe, set the attribute mobile_iframe to true:

FB.ui({
  method: 'share',
  mobile_iframe: true,
  href: 'https://developers.facebook.com/docs/',
}, function(response){});

Try it yourself!

URL Redirection

To share a link:

https://www.facebook.com/dialog/share?
  app_id=145634995501895
  &display=popup
  &href=https%3A%2F%2Fdevelopers.facebook.com%2Fdocs%2F
  &redirect_uri=https%3A%2F%2Fdevelopers.facebook.com%2Ftools%2Fexplorer

Note: When testing this code, remove the line breaks. Otherwise you will run into an error.

Open Graph actions

Trigger a Share Dialog using the FB.ui function with the share_open_graph method parameter to share an Open Graph story.

To share an Open Graph story with the dialog:

FB.ui({
  method: 'share_open_graph',
  action_type: 'og.likes',
  action_properties: JSON.stringify({
    object:'https://developers.facebook.com/docs/',
  })
}, function(response){});

Note that URL redirection works the same way as for standard link shares.

`share_open_graph` Parameters

Use the same parameters as for sharing a standard link, but add the following:

Parameter	Description
`action_type`	A string specifying which Open Graph action type to publish, e.g., `og.likes` for the built in like type. The dialog also supports approved custom types. Required when using method `share_open_graph`.
`action_properties`	A JSON object of key/value pairs specifying parameters which correspond to the `action_type` being used. Valid key/value pairs are the same parameters that can be used when publishing Open Graph Actions using the API. Required when using method `share_open_graph`.

The share_open_graph dialog does not support mobile_iframe: true.