Table of Contents
The SocialMagic component includes a number of Options which control its default behaviour. The options under the Basic and OpenGraph Tags tabs can be overridden at the category, content item, and menu item level.
Basic
OpenGraph images will be generated for all pages on your site unless explicitly configured not to, for example at the menu or article level. When disabled, you will have to explicitly configure menu items, articles, etc to generate OpenGraph images.
The OpenGraph image generation template to use. You have to save the plugin before selecting a template you just created or renamed. This option can be overridden in a menu item, category or article.
OpenGraph Tags
SocialMagick will add the OpenGraph namespace declaration to the <html> element of your site's HTML output. Leave enabled unless you have a custom template or a third party extension which does that for you. Even in this case it is safe to leave this option enabled; SocialMagick will check if the namespace declaration is present to avoid creating a duplicate definition.
If the OpenGraph namespace declaration is missing most third party sites and services will NOT be able to read the OpenGraph data of your site, even if this data is present in the <head> section of the HTML page.
Tells SocialMagic which text to use when setting the og:title property in the HTML document. This communicates the title of the current page to social media sites. Setting this to No disables this feature.
Tells SocialMagic which text to use when setting the og:description property in the HTML document. This communicates the summary (description) of the current page to social media sites. Setting this to No disables this feature.
Tells SocialMagic whether to set the og:url property in the HTML document. This communicates the URL of the current page to social media sites. This property is largely redundant for Joomla! sites. It only serves to satisfy OpenGraph validators which might complain if it's missing.
If you are not sure whether you need the OpenGraph URL or not, it's best to enable it. Having it when the consumer site / application doesn't need it doesn't hurt. Not having it when it's needed, though, may lead to undesired display of the links you share.
Tells SocialMagic whether to set the og:site_name property in the HTML document. This communicates the name of the site to social media sites.
Set the sharing card type on X (formerly Twitter). Summary shows the page title, description and a small thumbnail. Summary with Large Image is similar to Summary but uses a larger, prominent version of your page's OpenGraph image. If you use None X will show its default preview which may include a preview image. Using either card type requires that your page has an og:image property set either by this plugin or by a third party extension, otherwise it has no effect.
You can use this option even if you don't care about, plan to use, or support X; its properties are read by other social media sites and applications as a hint on how to best display a link preview.
The X handle used by your site, including the @ sign in front.
The default X handle which will be attributed as the content creator. Generally recommended to only set this in articles, not in the component Options.
If your site is using a Facebook app, e.g. for social login, you are recommended to enter the Facebook App ID here so that Facebook can attribute the links of your site to that Facebook app. If you have no idea what this is you can safely omit it.
Advanced
The image file type for generated OpenGraph images. PNG and JPG are universally supported. PNG generates massive files which preserve transparency, JPG (default) generates fairly small files with some visual artifacts and does not support transparency. WebP produces the smallest files with minimal visual artifacts and does support transparency, but some niche services and (usually older versions of) third party software may not be able to display WebP files. If you know your links won't be shared in any niche software / service (or don't care about them), we recommend switching this option to WebP for best quality and size.
As of the writing of this documentation (September 2025) all major third party services and applications support WebP, with a question about whether Discord supports lossless WebP (what you get with a quality setting of 90 or higher).
Controls the quality of the generated image by adjusting the compression level.
0 is the worst image quality, at the best compression rate and smallest image size, but is rarely usable. 100 is the best image quality, using no compression and the highest image size. The exact semantics of this option depend on the image format you chose to use.
PNG: This file format only has 10 lossless compression levels ranging from 0 (uncompressed) to 9 (maximum compression). Lossless means that there is no change in image quality at all, only a small impact on file size. SocialMagick maps image quality 0-10 to PNG compression level 9, 11-20 to PNG compression level 8, ..., 81-90 to PNG compression level 1, and 91-100 to PNG compression level 0. We recommend using image quality 0 (maximum compression) on most servers. On slow servers, use image quality 60 (compression level 4).
PNG compression depends heavily on the capabilities of the PHP graphics handling library and the content of the image. Busy images will see practically no size change across the entire range of Image Quality.
JPG: The JPG format uses a lossy compression algorithm. Image Quality levels below 30 are very strongly NOT recommended because the visual artifacts make them unusable. Moreover, an Image Quality beyond 85 makes the file significantly larger without any perceived improvement in quality. We recommend an image quality of 60 to 75. The default value (75) is the one recommended by the JPG standard.
WebP: Image Quality levels 0 to 89 use lossy compression which can affect image quality. Image quality 90 to 100 uses lossless compression which will result in fairly small files with no loss of image quality whatsoever. The default image quality (75) is a good balance between quality and file size. You can get significantly better quality at a small increase in file size using quality level 100, but some sites may not be able to display your OpenGraph image.
By default, SocialMagick only regenerates an OpenGraph image for a specific page when it detects that the text, Extra Image, template, or template settings have changed since the last time it generated an image for that page.
If you are troubleshooting and need to override this image caching behaviour, you need to enable this option. Please note that this has a very high impact on your site's performance as SocialMagick will try to generate images on every page load!
Enables the Debug Text Layout feature. This feature renders the text box and overlay text lines bounding boxes on the generated OpenGraph image. You should only enable that on development sites, always together with the Regenerate Images On Every Page Load (Development Mode) option.
Instead of using this option, we strongly recommend using the Template Preview feature when editing a template, enabling the Debug Text Layout checkbox for the Template Preview. Doing so will NOT affect your generated OpenGraph images and does not run the risk of a third party site or application showing and caching an OpenGraph image with the Debug Text Layout markings on it.
SocialMagick will display a preview floating on pages it has generated an OpenGraph image. Clicking on it allows you to preview the OpenGraph image and properties of the page without having to view source, or use a third party site / tool. You can choose which Joomla User Groups will see this button below. See Frontend Preview.
Choose the Joomla Access Level which will see the Frontend Preview Button. The default value is Special, allowing only Administrator and Super User accounts to see the button.
Choose which PHP extension to use to generate OpenGraph images. Use Auto-detect unless our support explicitly asks you to do otherwise. ImageMagick uses the imagick PHP extension (faster, you may have to ask your host to install or enable). GD uses the PHP gd extension (slower, installed on most servers). If your selected library is not available no images will be generated. Auto-detect uses ImageMagick if available, falls back to GD if not.
These options control the face detection feature used when the Crop Anchor Point of an Extra Image is set to Detect. Face detection lets SocialMagick automatically crop the Extra Image so that detected faces are well-framed in the OpenGraph image, without you having to pick a fixed anchor point. See the dedicated Face Detection section for a full description of the feature.
Choose which algorithm SocialMagick uses to detect faces in Extra Images. Three methods are available:
Pure PHP. A built-in, pure PHP implementation of the Viola-Jones cascade classifier algorithm. It requires no external services or credentials, has no running cost, and works on every server without additional configuration. It is the least accurate of the three methods and can be slow on underpowered hosting.
Google Cloud Vision API. Sends each Extra Image to Google's Cloud Vision service for face detection. Considerably more accurate than the Pure PHP method and generally faster. Requires a Google Cloud account and a valid API key with the Cloud Vision API enabled. Google Cloud Vision charges per image analysed; review Google's current pricing before enabling this option.
AWS Rekognition. Sends each Extra Image to Amazon Web Services' Rekognition service. Accurate and fast, similar to Google Cloud Vision. Requires an AWS account, an IAM user with rekognition:DetectFaces permission, and the Access Key, Secret Key, and Region entered below. AWS Rekognition charges per image analysed; review AWS's current pricing before enabling this option.
We recommend starting with Pure PHP. If the results are unsatisfactory for your content (for example, faces in angled portraits or lower-resolution images are missed), consider one of the cloud provider options.
Your API key for the Google Cloud Vision API. Only visible when Face Detection Method is Google Cloud Vision API. Create and manage keys in the Google Cloud Console; the key must have the Cloud Vision API enabled.
Your AWS access key ID. Only visible when Face Detection Method is AWS Rekognition. Create IAM credentials with the rekognition:DetectFaces permission in the AWS IAM console.
The AWS secret access key corresponding to the Access Key ID above.
The AWS region where Rekognition requests will be sent. Choose the region geographically closest to your web server for the best latency.
Auto-Image
The Auto-Image feature allows SocialMagick to automatically generate an image and assign it to an article's Intro Image and/or Full Text Image when you save an article that does not already have one. This gives every article a visually consistent image without requiring you to manually create one for each article you write. See the dedicated Auto-Image section for a full description.
Choose the Joomla Media Manager filesystem adapter where automatically generated article images will be saved. The default, Local - images, places files in your site's images directory. You can see available adapters in Joomla's Media Manager; each configured filesystem plugin exposes one or more adapters.
Use the default Local - images adapter unless you have a specific reason to do otherwise. Only images stored locally on the web server can later be used as an Extra Image source in SocialMagick templates.
The subdirectory within the Image Save Location where automatically generated images are stored. Defaults to socialmagick, producing a path of images/socialmagick when using the default adapter. SocialMagick creates the directory automatically if it does not exist.
Controls which article image field(s) SocialMagick should populate automatically.
Never. Auto-Image is disabled. No images are generated automatically when articles are saved. This is the default.
Intro Image Only. Generates and assigns an image to the Intro Image field when it is empty. The Full Text Image field is not affected.
Full Text Image Only. Generates and assigns an image to the Full Text Image field when it is empty. The Intro Image field is not affected.
Intro And/Or Full Text Image. Generates and assigns an image to each of the Intro Image and Full Text Image fields independently, wherever they are empty. If you have already provided an Intro Image but not a Full Text Image, only the Full Text Image is generated.
The SocialMagick template used when generating article images automatically. This setting can be overridden at the category and article level. The generated image uses the article title as its text overlay.
Choose a template that does not use the article's Intro Image or Full Text Image as its Extra Image source. Auto-Image runs at article-save time, before those fields have been set, so a template relying on them would produce an image with no Extra Image — which is almost certainly not what you want. A solid-colour card with only the title overlay, or a template using a static Extra Image, is the most suitable choice.