Verbb
You are viewing an older version of the Social Share documentation (1.x). View the latest version (2.x) →
Developers

GraphQL

Social Share supports accessing Share and Follower counts and Share Button and Button objects via GraphQL. Be sure to read about Craft's GraphQL support (opens new window).

Share Counts

Example

{
    socialShare {
        shares(handle: "facebook", url: "https://www.nytimes.com")
        twitterShares: shares(handle: "twitter", url: "https://www.nytimes.com")
    }
}
{
    "data": {
        "socialShare": {
            "shares": "4.1M",
            "twitterShares": "5.7M"
        }
    }
}

The shares query

This query is used to query for the Share count of a provided URL and a provider handle. The handle and url arguments are required.

ArgumentTypeDescription
handleStringNarrows the query results based on the shares provider’s handle.
urlStringNarrows the query results based on the URL to check shares for.
friendlyCountBooleanWhether the returned count should be a "friendly" number.
enableCacheBooleanWhether to enable the cache for results.
cacheDurationIntThe number of seconds to cache results for.

Follower Counts

Example

{
    socialShare {
        followers(handle: "facebook", account: "nytimes")
        twitterFollowers: followers(handle: "twitter", account: "nytimes")
    }
}
{
    "data": {
        "socialShare": {
            "followers": "18M",
            "twitterFollowers": "54.7M"
        }
    }
}

The followers query

This query is used to query for the Follower count of a provided account identifier and a provider handle. The handle and account arguments are required.

ArgumentTypeDescription
handleStringNarrows the query results based on the shares provider’s handle.
accountStringNarrows the query results based on the account to check followers for.
friendlyCountBooleanWhether the returned count should be a "friendly" number.
enableCacheBooleanWhether to enable the cache for results.
cacheDurationIntThe number of seconds to cache results for.

Share Buttons

Example

{
    socialShare {
        shareButtons(handle: ["facebook", "twitter"], url: "https://my-site.test") {
            url
        }

        shareButton(handle: "facebook") {
            name
            handle
            primaryColor
            icon
            url
        }
    }
}
{
    "data": {
        "socialShare": {
            "shareButtons": [
                {
                    "url": "https://www.facebook.com/sharer/sharer.php?u=https%3A//my-site.test"
                },
                {
                    "url": "https://twitter.com/intent/tweet?url=https%3A//my-site.test"
                }
            ],
            "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 shareButtons query

This query is used to query Share Button objects. You can also use the singular shareButton to fetch a single share button.

ArgumentTypeDescription
handle[String]Narrows the query results based on the button provider’s handle.
urlStringProvide the URL to be shared.
textStringProvide the text to be shared.
params[String]Provide any other params to be included in the share URL.

The ShareButtonInterface interface

This is the interface implemented by all share buttons.

FieldTypeDescription
nameStringThe button provider’s name.
handleStringThe button provider’s handle.
primaryColorStringThe button provider’s primary brand color.
iconStringThe button provider’s SVG icon.
urlStringThe button’s URL.

Buttons

Example

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

        button(handle: "facebook") {
            name
            handle
            primaryColor
            icon
        }
    }
}
{
    "data": {
        "socialShare": {
            "buttons": [
                {
                    "primaryColor": "#3b5997"
                },
                {
                    "primaryColor": "#1da1f2"
                }
            ],
            "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>",
            },
        }
    }
}

The buttons query

This query is used to query Button objects. You can also use the singular button to fetch a single button.

ArgumentTypeDescription
handle[String]Narrows the query results based on the button provider’s handle.

The ButtonInterface interface

This is the interface implemented by all buttons.

FieldTypeDescription
nameStringThe button provider’s name.
handleStringThe button provider’s handle.
primaryColorStringThe button provider’s primary brand color.
iconStringThe button provider’s SVG icon.
Last updated: May 4, 2026, 8:57:54 AM
Previous Button