Queries

Social Share lets a headless frontend fetch follower counts, share counts and button details through Craft’s GraphQL API. Every query sits inside a single socialShare query, which groups the plugin’s content together.

Set Up the Schema

In GraphQL → Schemas, edit the schema your frontend uses and enable Query Social Share under Social Share. Without it, the socialShare query isn’t part of the schema. Use GraphQL → GraphiQL with that schema to try the examples below, and see Craft’s GraphQL documentation (opens new window) for endpoints and tokens.

Follower and share counts need their provider configured first, as described in its provider guide, such as Facebook. GraphQL count queries always use the cache settings and request limits configured for the site.

Plugin Queries

The socialShare Query

Returns the Social Share content the schema can read. It takes no arguments, and you select followers, shares, shareButtons, shareButton, buttons or button inside it.

{
  socialShare {
    followers(handle: "facebook", account: "nytimes")
    shares(handle: "facebook", url: "https://www.nytimes.com")
  }
}

{
  "data": {
    "socialShare": {
      "followers": "18M",
      "shares": "4.1M"
    }
  }
}

The followers Query

Returns the follower count for an account on a provider, as a string. It returns null when the provider can’t fetch the count, and an account identifier longer than 255 bytes returns null without a request.

Use aliases to request several providers in one query:

{
  socialShare {
    facebook: followers(handle: "facebook", account: "nytimes")
    twitter: followers(handle: "twitter", account: "nytimes", friendlyCount: false)
  }
}

{
  "data": {
    "socialShare": {
      "facebook": "18M",
      "twitter": "54700000"
    }
  }
}

The shares Query

Returns the share count for a URL on a provider, as a string. It returns null when the provider can’t fetch the count, and a URL longer than 2048 bytes returns null without a request.

query Shares($url: String) {
  socialShare {
    shares(handle: "facebook", url: $url)
  }
}

{
  "url": "https://www.nytimes.com"
}

{
  "data": {
    "socialShare": {
      "shares": "4.1M"
    }
  }
}

The shareButtons Query

Returns a list of ShareButtonInterface objects, one for each provider handle, so your frontend can build its own share buttons. Each button’s url is the provider’s share link for the URL you pass.

{
  socialShare {
    shareButtons(handle: ["facebook", "linkedIn"], url: "https://my-site.test/news/launch") {
      name
      primaryColor
      url
    }
  }
}

{
  "data": {
    "socialShare": {
      "shareButtons": [
        {
          "name": "Facebook",
          "primaryColor": "#3b5997",
          "url": "https://www.facebook.com/sharer/sharer.php?u=https%3A//my-site.test/news/launch"
        },
        {
          "name": "LinkedIn",
          "primaryColor": "#0077b5",
          "url": "https://www.linkedin.com/shareArticle?url=https%3A//my-site.test/news/launch&mini=1"
        }
      ]
    }
  }
}

The shareButton Query

Returns a single ShareButtonInterface object. It takes the same arguments as shareButtons, and uses the first handle you pass.

{
  socialShare {
    shareButton(handle: "facebook", url: "https://my-site.test") {
      name
      handle
      primaryColor
      icon
      url
    }
  }
}

{
  "data": {
    "socialShare": {
      "shareButton": {
        "name": "Facebook",
        "handle": "facebook",
        "primaryColor": "#3b5997",
        "icon": "<svg fill=\"currentColor\" viewBox=\"0 0 320 512\"><path d=\"M279.14 288l14.22-92.66h-88.91v-60.13c0-25.35 12.42-50.06 52.24-50.06h40.42V6.26S260.43 0 225.36 0c-73.22 0-121.08 44.38-121.08 124.72v70.62H22.89V288h81.39v224h100.17V288z\"></path></svg>",
        "url": "https://www.facebook.com/sharer/sharer.php?u=https%3A//my-site.test"
      }
    }
  }
}

The buttons Query

Returns a list of ButtonInterface objects, one for each provider handle. Use these for buttons that link to your own profiles, where you supply the link yourself.

{
  socialShare {
    buttons(handle: ["facebook", "linkedIn"]) {
      name
      primaryColor
    }
  }
}

{
  "data": {
    "socialShare": {
      "buttons": [
        { "name": "Facebook", "primaryColor": "#3b5997" },
        { "name": "LinkedIn", "primaryColor": "#0077b5" }
      ]
    }
  }
}

The button Query

Returns a single ButtonInterface object. It takes the same handle argument as buttons, and uses the first handle you pass.

{
  socialShare {
    button(handle: "facebook") {
      name
      handle
      primaryColor
      icon
    }
  }
}

{
  "data": {
    "socialShare": {
      "button": {
        "name": "Facebook",
        "handle": "facebook",
        "primaryColor": "#3b5997",
        "icon": "<svg fill=\"currentColor\" viewBox=\"0 0 320 512\"><path d=\"M279.14 288l14.22-92.66h-88.91v-60.13c0-25.35 12.42-50.06 52.24-50.06h40.42V6.26S260.43 0 225.36 0c-73.22 0-121.08 44.38-121.08 124.72v70.62H22.89V288h81.39v224h100.17V288z\"></path></svg>"
      }
    }
  }
}