Skip to main content

Twitter Cards

Open Graph gave you control over how your link looks when it is shared. Twitter Cards do the same job for one particular place: the platform that was once called Twitter, and is now called X.

The good news is that you do not have to start from scratch. X reads Open Graph tags as a fallback, so most of the work is already done. You add a small number of twitter: tags to switch the card on and fine-tune it. This lesson shows you which ones, and which you can skip.


What You Will Learn​

  • What Twitter Cards are, and how they relate to Open Graph
  • The two card types you will actually use
  • The key tags: card, title, description, image, alt, site, and creator
  • How the fallback order works, so you write less
  • Image sizes for each card
  • Why robots.txt must allow Twitterbot
  • How to test your cards

The Big Idea​

index.html
<head>
  <title>Easy No-Knead Rye Bread | The Bread Bin</title>

  <!-- Open Graph does most of the work -->
  <meta property="og:title" content="Easy No-Knead Rye Bread">
  <meta property="og:description" content="Bake a crusty rye loaf at home with five simple ingredients.">
  <meta property="og:image" content="https://thebreadbin.example/img/rye-1200x630.jpg">

  <!-- One tag switches on a large card, and one names your account -->
  <meta name="twitter:card" content="summary_large_image">
  <meta name="twitter:site" content="@thebreadbin">
  <meta name="twitter:image:alt" content="A rye loaf cooling on a wooden board">
</head>

Switch between the two card types, and tick "Use my Open Graph tags" to see the lean setup.

A note on the name

The platform has been renamed X, but the tags still begin with twitter:, and the feature is still widely called Twitter Cards. Always check X's current developer documentation, because names and details can change.

What Twitter Cards Are​

A Twitter Card is the preview that appears under a link in a post: a picture, a title, and a line of description, instead of just a bare address. The card is built from <meta> tags in your page's head, read by X's crawler (called Twitterbot) when the link is shared.

  • Like Open Graph, cards do not directly affect your search ranking. They make shared links more inviting.
  • Unlike Open Graph, the conventional attribute is name, not property: <meta name="twitter:card" ...>.
  • Other apps do not usually read them. Chat apps, Slack, Discord, WhatsApp, and Mastodon mostly use Open Graph. That is one more reason to write good Open Graph tags first.

The Card Types​

CardWhat it looks likeBest for
summaryA small square picture beside the title and descriptionPages without a strong picture, or with a logo
summary_large_imageA large picture above the title and descriptionArticles, recipes, products, and anything with a good image

Two other types (app and player) exist for specialised uses, and have limited support today. Most pages only ever need one of the two above. When in doubt, use summary_large_image.

The Tags​

TagWhat it does
twitter:cardThe one that turns the card on. Its value is the card type
twitter:titleThe headline of the card
twitter:descriptionA line or two of text
twitter:imageThe picture
twitter:image:altA text description of the picture
twitter:siteThe account for the website (@thebreadbin)
twitter:creatorThe account of the author (@ravipatel)

Handles are written with an @ sign, and X handles are letters, numbers, and underscores, up to 15 characters.

Fallbacks: Write Less​

If a twitter: tag is missing, X usually falls back to the matching Open Graph tag, and then to the page itself:

NeededFirst choiceThenThen
Titletwitter:titleog:titlethe page <title>
Descriptiontwitter:descriptionog:descriptionthe meta description
Imagetwitter:imageog:imagenothing

The one thing that does not have a fallback is twitter:card. Without it, you may get only a plain link, even if your Open Graph tags are perfect.

So the lean setup is:

  1. Write good Open Graph tags.
  2. Add twitter:card.
  3. Optionally add twitter:site and twitter:image:alt.

Add the full set of twitter: tags only when you want the card to say something different from your Open Graph tags.

Play with the fallbacks, and see which tag wins:

http://127.0.0.1:5500/index.html
Which tags does your page have?

What a card is likely to use:

  • Card: A rich card (the type named in twitter:card).
  • Title: og:title
  • Description: og:description
  • Image: og:image

This is the lean, popular setup: your Open Graph tags do the work, and one extra tag turns on the card.

This shows the commonly documented order of fallbacks, from the most specific tag to the least. Platforms can change their behaviour at any time, so check the current documentation and test your page.

Images​

Per X's public guidance (check the current documentation, as sizes change):

CardShapeSuggested sizeNotes
summary_large_imageAbout 2 to 11200 by 600 is a good target. At least 300 by 157Larger images get cropped to fit
summarySquare, 1 to 1At least 144 by 144. 600 by 600 is a good targetShown as a small thumbnail
  • Formats: JPG, PNG, WebP, and GIF (usually the first frame). Not SVG.
  • File size: keep it well under a few megabytes. Smaller is faster.
  • Full https address, public, with no login.
  • Keep key content in the middle, since edges may be cropped.
  • Use an image of about 2 to 1 for both Open Graph and Twitter if you want one file to serve both. A 1200 by 630 image (Open Graph's usual size) is close enough to 2 to 1 for a large card, and many sites use it for both.
  • Add twitter:image:alt so the image has a description. X limits alt text length, so keep it short and plain.

Do Not Block Twitterbot​

X's crawler obeys your robots.txt. If your file blocks it, or blocks the folder where your images live, cards will fail to appear.

robots.txt
# This would break cards
User-agent: Twitterbot
Disallow: /

Check that Twitterbot is allowed on your pages and on your image address. See Robots Meta. Also remember that pages and images behind a login cannot be fetched, so cards for them show nothing.

Caching and Testing​

  • X caches cards, like other platforms. After you change a tag or image, an old card may linger for a while. Using a new image address (such as a version number in the file name) is the most reliable fix.
  • X has retired its old Card Validator tool, so do not rely on it. Check X's current help pages in case a new one exists. The most reliable test is to draft a post with your link in it, and look at the preview before you publish. Check X's current help pages for any new tool.
  • Test the Open Graph tags too, with the Facebook Sharing Debugger and the LinkedIn Post Inspector. If your Open Graph is right, the fallback works.

Check Your Tags​

http://127.0.0.1:5500/index.html

Check it for real​

  1. "View source" on the live page, and search for twitter:.
  2. Draft a post on X with your link, and read the preview.
  3. Open your image address in a private window. Does it load without logging in?
  4. Open /robots.txt on your site, and make sure Twitterbot is not blocked.
  5. Check Open Graph in a debugger, since the fallback depends on it.

Twitter Cards in Docusaurus​

Docusaurus lets you set a card type for the whole site (in the theme's configuration, using metadata or the social card options), and uses a page's title, description, and image for the matching tags. You can also add twitter: tags to a single page with the Head component. The tags end up in the built HTML. Details change between versions, so check the current documentation and inspect the output.

Good Habits​

  • Write complete Open Graph tags first.
  • Add twitter:card to every page, usually summary_large_image.
  • Add twitter:site and twitter:image:alt.
  • Use a good, public, wide image with a full https address.
  • Only add twitter:title and the like when the card should differ.
  • Allow Twitterbot in robots.txt.
  • Preview a draft post before you publish.
  • Use a new image address when you change an image.

Twitter Cards Checklist​

  • twitter:card is on every page, with summary or summary_large_image
  • Open Graph title, description, and image are set (or the twitter: versions)
  • The image is JPG, PNG, WebP, or GIF, public, with a full https address
  • The image shape matches the card type
  • twitter:image:alt is set
  • twitter:site and twitter:creator are valid handles, with an @ sign
  • Twitterbot is allowed in robots.txt
  • Tags use name and appear once
  • Tags are in the HTML the server sends
  • A draft post showed the preview correctly
  • No private data is in any tag

Security and Privacy Notes​

  • Escape every value. If a title or description comes from a database or a user, a stray quote or angle bracket can break your tags and inject content. Escape before you write it into content="...". The builder above does this.
  • Handles identify real people. twitter:creator links a page to a person's account. Only use a handle with the person's consent, and prefer your organisation's account over a personal one.
  • Private pages leak through cards. If someone shares a link to a private page, X may fetch it and show its title and image to everyone. Put generic text in the tags of logged-in pages, and do not expose private details.
  • Pictures can reveal more than you expect. Check images for names, faces, and locations, and remove hidden location data (EXIF) from photos.
  • Do not mislead. A card that says one thing while the page says another may be treated as spam or a scam by the platform.
  • Do not put tracking codes in the image address that identify individual visitors. The card is shown to many people.
  • Watch for tampering. If a hacked page has its tags changed, shared links can show spam. Check your live tags from time to time.
  • Crawlers appear in your logs. Twitterbot fetching your page is normal. If you restrict access by address or user agent, allow it deliberately.

Global Audience Notes​

  • Write each language version's tags in that language, and give it its own image if the picture contains text.
  • Check where your readers share. X is not equally popular everywhere, and other apps (which read Open Graph) may matter more. Do not neglect Open Graph.
  • Text direction: cards for right-to-left languages such as Arabic and Hebrew should be tested in the real preview.
  • Titles and descriptions are cut at different lengths in different scripts. Preview each language.
  • Handles are not translated. Use the account that matches the audience, such as a separate account per language, if you have one.
  • Slow networks: a large image may be slow to load or fail on a poor connection. Keep files small.
  • Access and rules vary by country. The platform may be limited or unavailable in some places. Do not depend on it as your only channel.

Common Mistakes to Avoid​

  1. No twitter:card tag, so no card appears.
  2. Relying on Open Graph alone, and forgetting the card tag.
  3. A relative or SVG image.
  4. An image of the wrong shape, which gets cropped badly.
  5. Handles without the @, or with spaces.
  6. Blocking Twitterbot in robots.txt.
  7. A private or login-protected image.
  8. Using property instead of name.
  9. Duplicate tags that disagree.
  10. A stale card that is never refreshed.
  11. No alt text for the image.
  12. Never previewing the card before posting.

Practice Time​

Try these in your browser and your editor:

  1. Use the builder with each card type. How does the image shape change?
  2. Tick "Use my Open Graph tags," and see which tags remain.
  3. In the fallback lab, remove twitter:card. What happens to the result?
  4. Run the checker on the messy page, fix every problem, and run it again.
  5. Add twitter:card to a page that already has Open Graph tags.
  6. Check your robots.txt for Twitterbot.
  7. Draft a post on X with a link to your page, and look at the preview. Do not publish it.
  8. Make one image that works for both a large card and Open Graph, and keep the text in the middle.
  9. Write alt text for your share image in under a hundred characters.
  10. Bonus: make a different image for each language version of a page, and add the matching tags.

Quick Recap​

Click a question to check your answer.

1. What are Twitter Cards?

Meta tags that tell X how to draw a preview card (picture, title, description) under a shared link.

2. Which tag turns the card on?

twitter:card, with a value such as summary_large_image. It has no fallback, so without it you may only get a plain link.

3. How do Twitter Cards relate to Open Graph?

X falls back to Open Graph for the title, description, and image when the twitter: versions are missing. So you can write good Open Graph tags and add only twitter:card.

4. Which card types should most pages use?

summary_large_image for pages with a good picture, and summary for small square images such as logos.

5. Why must robots.txt allow Twitterbot?

Twitterbot obeys robots.txt. If it is blocked from your page or your image, the card cannot be built.

6. How can you test a card?

Draft a post with your link and look at the preview before publishing. Check X's current help pages for any official tool, and test your Open Graph tags in the other platforms' debuggers.

Key Takeaways​

  • Twitter Cards control how your link looks on X. The tags still use the twitter: prefix.
  • twitter:card is the key tag, and it has no fallback.
  • Open Graph is the fallback for title, description, and image, so write it first.
  • Use summary_large_image for most pages, with a wide image of about 2 to 1.
  • Use full, public https addresses, and never SVG.
  • Allow Twitterbot in robots.txt.
  • Escape values, and keep private pages out of cards.
  • Preview a draft post before you publish.

Next, the last lesson in this section, learn how to serve readers in many languages and regions, in International SEO.