# GitHub README banner: a header image for your repo [Canonical HTML page](https://gradiently.design/guide/github-readme-banner) GitHub never published a README banner size. Choose a frame that can share a ground with your social preview, then export a light file and a dark file. ## The short version - GitHub publishes no README banner size. The image scales to the column, so the ratio sets the header height. - A useful convention is 1280×640, the frame GitHub recommends for the social preview, or a wider 1600×640, or a slimmer 1600×400. - Embed one image with Markdown. For light and dark mode, use a picture element with prefers-color-scheme and one file per theme. - Keep each file under 1 MB if it may also be the social preview, and put the banner's words in the alt when the README does not repeat them. - The banner is not the link card. Upload a separate 1280×640 image under Social preview, with the same ground, name and line. A **GitHub README banner** is the wide image at the top of a repository README. GitHub publishes no width or height for it. The useful conventions are **1280×640**, the social preview frame, a wider **1600×640**, and a slimmer **1600×400**. One file is a Markdown image: an exclamation mark, the alt in brackets, then the path in parentheses, with nothing between them. Two themes need the HTML below. The shared-link card is a different upload, and it should use the same name, line and ground. - Social card 1280×640: 1280 × 640 - Wide header 1600×640: 1600 × 640 - Slim header 1600×400: 1600 × 400 - Preview minimum 640×320: 640 × 320 1280×640 and the 640×320 floor are the social preview. The wider frames are README conventions, not sizes GitHub publishes. ## Sizes people use for a README banner GitHub scales the image down to the column and does not crop it to a slot. A 2:1 image ends up half as tall as the column is wide. A 2.5:1 image is shorter, and a 4:1 image is about half the height of the 2:1. Extra pixels keep type sharp on a high density screen. They do not make the banner bigger. | Asset | Size | What it actually is | | --- | --- | --- | | README banner | No published size | Convention. Any image at the top. | | Social preview | 1280×640, under 1 MB | Documented. At least 640×320. PNG, JPG or GIF. | | Wide header | 1600×640 | Convention. 2.5:1. | | Slim header | 1600×400 | Convention. 4:1, so the intro stays visible. | | README file | Cut off past 500 KiB | Documented. The Markdown, not the image. | Social preview size and the 500 KiB cutoff are GitHub's. Banner sizes are choices. Use **1280×640** when one layout should do both jobs. GitHub recommends it for the social preview, with 640×320 as the floor, and on the repo page that ratio is a tall header. Use **1600×640** for a wider ground, or **1600×400** when the image is only a signature. Around 1280 to 1600 px wide is enough. A wide 1600 by 640 README banner reading Keel, with the line A preview for every pull request, on a gradient A 1600×640 header. The same words go on the social card, with more ground around them. A 1280 by 640 social preview reading Keel, with the same line and the same gradient as the README banner The same words at 1280×640, kept out of the corners a shared card often crops. - **The name**, still readable after the column shrinks the image. - **One line** about what it does, repeated in About. - **One ground** for the card, the docs and the site. - **The name in the middle**, clear of the crop. - **No stale numbers.** Stars and versions go under the image, in Markdown. ## How to embed the banner Commit a PNG beside the README and use a relative path. GitHub rewrites it for the current branch. A path starting with `/` is from the repo root. For the fictional project Keel, the file is `./assets/keel-banner.png`. Markdown sets no width, so the column scales it. The alt is the banner's own words. Markdown cannot swap files by theme. GitHub's writing quickstart uses the HTML [picture element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture): a dark source, a light source, and an img for when picture is ignored. The test is [prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme). GitHub's dark theme matches the dark value, and the browser downloads only the source that matches. ```html Keel: a preview for every pull request. ``` The quickstart pattern, with relative paths. The alt sits on the img. The light file is the fallback. Leave a blank line before and after the picture, so Markdown treats it as HTML. Both files must say the same thing, because there is only one alt. Point `src` at the light file so a renderer that skips picture still shows a banner. GitHub also honours `#gh-dark-mode-only` and `#gh-light-mode-only`, added in November 2021. They work only on GitHub. Prefer picture, and keep both images on one line if you use the fragments. > **Keep the image out of the Markdown** GitHub truncates a README past 500 KiB. That cap is the Markdown, not the PNG, so store the image as its own file. ## Light mode and dark mode An opaque banner brings its own ground. The miss is a bright slab on a dark README, or a dark slab on a light one. Export twice: a deeper ground and light type for dark mode, the reverse for light mode, same words. Do not invert the file. A calm colour can turn harsh. See [dark mode design](https://gradiently.design/guide/dark-mode-design) and [contrast](https://gradiently.design/guide/color-contrast-accessibility). ### Avoid - One white banner for both themes - A black wordmark with no light twin - An inverted copy of the light file - Different lines on the two files ### Do - The same words on both files - A light ground and a dark ground - Dark type on light, light type on dark - One alt that is true for both - Light ground: `linear-gradient(135deg, #f4fcfb 0%, #c5ebe4 50%, #8fd0c4 100%)` - Dark ground: `linear-gradient(160deg, #042422 0%, #0c4741 52%, #14685c 100%)` One teal, rebuilt for each theme, then exported as two PNGs. The embed will not paint a CSS background for you. Or use a wordmark with no ground: dark letters for light mode, light letters for dark mode, on a clear background so the page colour shows through. Keep a solid ground on the social card. [Wordmarks](https://gradiently.design/guide/wordmark-design) covers the lettering. ## File weight and alt text GitHub sets no byte limit on a README banner. It warns above 50 MiB, blocks a file over 100 MiB, and stops a browser upload at 25 MiB. Stay far under those. The social preview should be under 1 MB, so keep each banner under 1 MB too. Use PNG for type on a flat or gradient ground, and JPG for a photo. The social preview accepts PNG, JPG or GIF, not SVG. A relative SVG can show in the README, but it cannot be that upload. See [PNG vs JPG](https://gradiently.design/guide/png-vs-jpeg), [SVG vs PNG](https://gradiently.design/guide/svg-vs-png) and [image compression](https://gradiently.design/guide/image-compression). Alt is a short equivalent of the image, on the img only. If the tagline is only on the banner, the alt is the name plus that line. If the heading repeats both, leave it empty. Do not write "banner". [WebAIM's alt text guide](https://webaim.org/techniques/alttext/) is the rule, and the one alt must stay true for both files. ## Match the banner to the social preview The banner is what you embed. Upload the social preview in **Settings**, under **Social preview**, then **Edit** and **Upload an image**. GitHub asks for PNG, JPG or GIF under 1 MB, at least 640×320, and 1280×640 for the best display. Only a public repo shares it. Transparency is allowed, but app backgrounds differ, so use an opaque ground. Crops and stale cards are covered in [GitHub social preview](https://gradiently.design/guide/github-social-preview). 1. **Write the line once** Name plus one sentence: that is the banner, the alt, the card and About. 2. **Design the 1280×640 card first** Put the name in the centre, with a margin. Apps crop the sides, and some keep the middle square. 3. **Make the README frame from the same ground** Keep 1280×640, or move to 1600×640 or 1600×400. Export again. Do not squash the card. 4. **Export a light file and a dark file** Same words, two grounds. Commit both PNGs next to the README. 5. **Embed, then upload the card** Paste the HTML and toggle the theme. Then upload the opaque 1280×640 PNG under Social preview. Use one ground everywhere the project appears. [Open source project branding](https://gradiently.design/guide/open-source-project-branding) is the wider system. The banner is only the piece above the install steps. You can build both frames in Gradiently. Start a blank design at a custom size, from 200 to 8,000 px, on a Mark. It moves a calm area behind the type, and Auto ink picks light or dark letters from its palette. Export a PNG per theme and a 1280×640 card. A transparent PNG drops the Mark, is part of Pro, and still needs one file per theme. See [exporting SVG and transparent PNG](https://gradiently.design/guide/export-svg-transparent-png). ## FAQ ### What size is a GitHub README banner? GitHub publishes none. Conventions that work are 1280×640, a wider 1600×640, or a slimmer 1600×400 so the introduction stays on screen. ### How do I add a banner image to a README? Commit a PNG and embed it with Markdown, or with a picture element when you have a light file and a dark file. Use a relative path so the image follows the branch. ### How do I make a README banner work in dark mode? Export the same layout twice, one light ground and one dark ground, and switch them with picture and prefers-color-scheme. A single black wordmark on a clear background disappears in dark mode. ### Does the README banner show when I share the repo? No. The shared card is the social preview, uploaded under Settings, then Social preview. GitHub recommends 1280×640 as a PNG, JPG or GIF under 1 MB, and only a public repo shares it. ### What alt text should a README banner use? Use the name and the line on the image when the README does not already say them. If the heading repeats both, leave the alt empty so a screen reader does not announce them twice. ### How big should the banner file be? No README-specific limit. Keep each file under 1 MB so it can also be the social preview, and store it outside the Markdown, which GitHub cuts past 500 KiB.