Working with Images
What You'll Learn
Best practices for adding images to your HubSpot pages, including optimal sizing, file formats, alt text for accessibility, and the difference between background and inline images.
Before You Start
- Have your images ready and properly sized
- Know where each image will be used (hero, card, background, etc.)
- Prepare descriptive alt text for each image
- Ensure you have rights to use all images
Image Types in HubSpot
Inline Images (Content Images)
Images that are part of your page content, displayed within text or in specific image modules.
When to use:
- Product photos
- Team member headshots
- Screenshots or diagrams
- Any image that conveys specific information
Background Images
Images that appear behind other content, typically covering a full section.
When to use:
- Hero sections with text overlay
- Decorative section backgrounds
- Card backgrounds in Featured Card Group
Recommended Image Sizes
| Use Case | Dimensions | Max File Size |
|---|---|---|
| Hero background (full width) | 1920 x 1080 px | 300 KB |
| Hero background (retina) | 2560 x 1440 px | 500 KB |
| Card image | 600 x 400 px | 100 KB |
| Card image (retina) | 1200 x 800 px | 200 KB |
| Company logo (testimonials) | 200 x 100 px | 50 KB |
| Custom icon (SVG) | 64 x 64 px | 10 KB |
| Blog featured image | 1200 x 630 px | 200 KB |
| Inline content image | 800 px wide (max) | 150 KB |
Step-by-Step: Adding Images
Adding a Background Image
- Select the section or module that supports background images
- Look for Background settings in the module panel
- Choose Background Type: Image
- Click Choose image to open the file manager
- Upload your image or select from existing files
- Adjust any overlay or positioning options if available
What you'll see: Your image appears behind the section content.
Adding an Inline Image
- In a rich text editor, click where you want the image
- Click the Insert Image icon in the toolbar
- Upload your image or select from existing files
- Set the image size (original, fit to content, or custom)
- Add alt text in the image properties
What you'll see: Your image appears inline with your text content.
Adding a Logo Image
- Find the logo/image field in your module
- Click the image selector
- Upload your logo file (PNG with transparency recommended)
- Add alt text (e.g., "Company Name logo")
What you'll see: Your logo displayed in the module.
Writing Effective Alt Text
Alt text (alternative text) describes images for screen readers and displays when images fail to load.
Good Alt Text Examples
| Image | Good Alt Text | Poor Alt Text |
|---|---|---|
| Team photo at conference | "Marketing team presenting at Digital Summit 2024" | "team photo" |
| Product screenshot | "Dashboard showing monthly revenue analytics chart" | "screenshot" |
| CEO headshot | "Jane Smith, CEO of Acme Corp" | "headshot" |
| Decorative background | "" (empty - decorative images need no alt) | "background image" |
Alt Text Guidelines
Do:
- Describe what the image shows, not what it is
- Keep it concise (under 125 characters)
- Include relevant keywords naturally
- Leave alt text empty for purely decorative images
Avoid:
- Starting with "Image of..." or "Picture of..."
- Using file names as alt text
- Stuffing keywords unnaturally
- Repeating information already in surrounding text
File Format Guide
| Format | Best For | Notes |
|---|---|---|
| JPG/JPEG | Photos, complex images | Good compression, no transparency |
| PNG | Logos, graphics with transparency | Larger files, supports transparency |
| SVG | Icons, simple graphics | Scalable, very small file size |
| WebP | Modern replacement for JPG/PNG | Better compression, good browser support |
| GIF | Simple animations | Limited colors, avoid for photos |
Optimizing Images for Web
Before Uploading
- Resize to correct dimensions - Do not upload a 4000px image for a 400px space
- Compress the file - Use tools like TinyPNG, ImageOptim, or Squoosh
- Choose the right format - JPG for photos, PNG for graphics with transparency
- Use descriptive file names - "team-meeting-2024.jpg" not "IMG_1234.jpg"
Compression Tips
| Original Size | Target Size | Compression Level |
|---|---|---|
| 2 MB+ | Under 300 KB | High compression needed |
| 500 KB - 2 MB | Under 200 KB | Medium compression |
| Under 500 KB | Under 100 KB | Light compression |
Tips and Best Practices
- Always provide alt text for meaningful images
- Use consistent aspect ratios for grids and sliders
- Test page load speed after adding images
- Consider mobile users - large images slow down mobile loading
- Use HubSpot's image optimization features when available
- Create retina versions (2x size) for high-resolution displays
- Maintain brand consistency with image style and filters
Troubleshooting
Problem: Image looks blurry or pixelated. Solution: Upload a larger source image. The minimum size should match your display size; for retina displays, use 2x the display dimensions.
Problem: Image takes too long to load. Solution: Compress the image file. Aim for under 200 KB for most uses. Use JPG instead of PNG for photographs.
Problem: Image dimensions are distorted. Solution: Ensure your source image has the correct aspect ratio for its container. Crop or resize before uploading.
Problem: Background image does not show behind text. Solution: Check that Background Type is set to "Image" and not "Preset" or "None". Verify the image uploaded successfully.
Problem: Logo has a white box around it. Solution: Use a PNG file with a transparent background instead of a JPG.
Problem: Image alt text is not appearing. Solution: Alt text is only visible to screen readers and when images fail to load. This is normal behavior - it is working behind the scenes for accessibility.
Problem: Cannot upload image - file type not supported. Solution: Convert your image to JPG, PNG, or GIF format. HubSpot accepts most standard web image formats.
Problem: Images look different in preview vs. live page. Solution: Clear your browser cache and check the live page. Preview may use cached versions of older images.