Verbb
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")
    }
}
{
    "data": {
        "socialShare": {
            "shares": "4.1M"
        }
    }
}

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.

GraphQL count queries always use the cache policy and request budgets configured by the site. URLs longer than 2048 bytes resolve to null before Social Share reads or writes the count cache. The enableCache and cacheDuration arguments remain available so existing queries continue to validate, but they are ignored and will be removed in the next major version.

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.
enableCacheBooleanRetained for query compatibility but ignored. The site’s Social Share settings control result caching.
cacheDurationIntRetained for query compatibility but ignored. The site’s Social Share settings control the cache duration.

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.

GraphQL count queries always use the cache policy and request budgets configured by the site. Account identifiers longer than 255 bytes resolve to null before Social Share reads or writes the count cache. The enableCache and cacheDuration arguments remain available so existing queries continue to validate, but they are ignored and will be removed in the next major version.

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.
enableCacheBooleanRetained for query compatibility but ignored. The site’s Social Share settings control result caching.
cacheDurationIntRetained for query compatibility but ignored. The site’s Social Share settings control the cache duration.

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: Oct 5, 2026, 9:08:40 AM
Previous Custom Provider Next Provider