The CSS to overlay text on images in WordPress

Creating a text-overlay CSS solution for images is a common requirement in web development. After years of implementing CSS image text-overlay techniques across various WordPress sites, I eventually built Image Source Control to add image text overlays for author attributions. As a developer, I still understand those who want to develop their own text-overlay CSS for images in WordPress, so I am happy to share my library of solutions below.

Please note that this post is dedicated to developers who know CSS, where to add it, and how to change it. If you need custom help, you can reach out about a custom job or use Image Source Control to place text overlays on images without coding skills.

My examples are based on the Twenty Twenty-Four theme.

Understanding WordPress Image Markup

Before implementing any CSS overlay text on images, you must understand WordPress’s HTML structure. The markup has evolved over the years, and your CSS needs to account for modern and legacy implementations. Here’s what you’re working with:

<!-- Block Editor (Gutenberg) Image -->
<figure class="wp-block-image size-full">
    <img src="image.jpg" alt="Description" class="wp-image-123"/>
    <figcaption class="wp-element-caption">Image caption</figcaption>
</figure>

<!-- Classic Editor Image -->
<div class="wp-caption">
    <img src="image.jpg" alt="Description"/>
    <p class="wp-caption-text">Image caption</p>
</div>Code language: HTML, XML (xml)

This markup structure is crucial because it determines how your text overlay CSS will interact with the content.

Remember that themes and plugins could hook into this markup and change it.

Basic Text Overlay Solution

Start with these foundational styles when adding a CSS image overlay text effect. This approach provides a clean, professional look while maintaining readability:

/* Container styling */
.wp-block-image {
    position: relative;
}

/* Basic overlay styling */
.wp-block-image .wp-element-caption {
    position: absolute;
    bottom: 0;
    left: 0;
    right: 0;
    background: rgba(0, 0, 0, 0.7);
    color: #fff;
    padding: 10px;
    margin: 0;
    font-size: 14px;
    line-height: 1.4;
}Code language: CSS (css)

This is how it looks.

An example of an image text overlay styled with CSS.

This base CSS creates a semi-transparent overlay that works well across different image types and sizes. The absolute positioning ensures your text overlay stays anchored to the image, while the background provides sufficient contrast for readability.

Handling Different Types of Overlays

Text overlay CSS can be implemented in various ways depending on your needs. These variations provide solutions for different use cases, whether you’re creating attribution overlays, decorative text, or informational captions. Add the appropriate section to the CSS above to add the effect.

The overlay fully covers the image

.wp-element-caption {
    top: 0;
    display: flex;
    align-items: center;
    justify-content: center;
    text-align: center;
}Code language: CSS (css)

A smooth gradient in the overlay

.wp-element-caption {
    background: linear-gradient(
        to bottom,
        rgba(0, 0, 0, 0) 0%,
        rgba(0, 0, 0, 0.7) 100%
    );
    padding-top: 30px;
}Code language: CSS (css)

The overlay is in the bottom left corner

.wp-element-caption {
    left: auto;
    right: 0;
    max-width: 50%;
    border-top-left-radius: 3px;
}Code language: CSS (css)

Each of these CSS image text overlay variations serves a specific purpose. The gradient overlay works particularly well for longer text, while the corner overlay is perfect for short attributions or watermarks. The full overlay style is ideal for creating dramatic, magazine-style image treatments.

Responsive Design Considerations

A CSS overlay text on images must work across all devices. Mobile optimization isn’t optional – it’s essential for modern websites. Here are a few text overlay CSS blocks to get you started.

/* Base responsive rules */
@media (max-width: 768px) {
    .wp-block-image .wp-element-caption {
        font-size: 12px;
        padding: 8px;
    }
}

/* Handle very small screens */
@media (max-width: 480px) {
    .wp-block-image .wp-element-caption {
        position: relative;
        background: #f0f0f0;
        color: #333;
    }
}Code language: CSS (css)

These responsive rules ensure your text overlays remain readable and aesthetically pleasing across all screen sizes. The mobile-first approach prevents common issues like text-overflow and maintains proper contrast ratios on smaller screens.

Handling Theme Conflicts

When implementing text overlay CSS, theme conflicts can be your biggest challenge. These rules help maintain consistency across different WordPress themes:

/* Force proper positioning */
.wp-block-image {
    display: block !important;
    overflow: hidden;
}

/* Ensure the image sits correctly */
.wp-block-image img {
    display: block;
    width: 100%;
    height: auto;
}

/* Fix z-index issues */
.wp-block-image .wp-element-caption {
    z-index: 2;
}Code language: CSS (css)

These overrides prevent common theme-related issues like broken positioning and z-index conflicts. They’re especially useful when working with WordPress themes that might have their own image styling.

It is worth noting that galleries don’t have much different markup than individual images in the content.

However, at least in the default themes, the text caption is already listed as an overlay. You’d only need additional CSS to adjust that. Let me know if you’d like to see an example.

Print Stylesheet Considerations

While not an everyday use case, you might also want to consider the styling of CSS image text overlays on print layouts.

@media print {
    .wp-block-image .wp-element-caption,
    .blocks-gallery-grid .blocks-gallery-item__caption {
        position: relative;
        background: none !important;
        color: #000 !important;
        padding: 5px 0;
    }
}Code language: CSS (css)

These print styles ensure your content remains readable and professional when printed, converting overlay effects into simple, printer-friendly text placements.

Accessibility Enhancements

Text overlay CSS must prioritize accessibility. These enhancements ensure your overlays are readable by all users:

.wp-block-image .wp-element-caption {
    /* Ensure sufficient contrast */
    text-shadow: 1px 1px 1px rgba(0, 0, 0, 0.5);
    
    /* Better readability */
    font-weight: 500;
    letter-spacing: 0.02em;
}Code language: CSS (css)

Good accessibility isn’t just about contrast ratios – it’s about ensuring your text overlays are readable by screen readers and maintaining proper focus states for interactive elements.

No-coding solutions

Check out the image text overlay features in my Image Source Control plugin to display your captions in a unified style, including images outside the content and powerful editing options.

The plugin is used by small and large publishers around the globe to display image captions in overlays without the need for coding skills.

Image Source Control also makes sure that your captions are always visible and synched among all posts, since doing that manually is easily forgotten.

Conclusion

While manually implementing a CSS overlay text on an image gives you complete control, it can become challenging to manage at scale. Consider automated solutions like Image Source Control for larger WordPress sites to maintain consistency across thousands of images.

Remember that successful text overlay implementation requires balancing aesthetic appeal with functionality. The CSS solutions provided here give you a solid foundation on which to build based on your specific needs.

Portrait of Thomas Maier, founder and CEO of Image Source Control

Questions? Feedback? How can I help?

Reach out directly via the contact form.