Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


This gatsby-transformer-remark plugin allows you to link images in custom components in a similar fashion to gatsby-remark-image.


npm install gatsby-remark-custom-image-component
yarn add gatsby-remark-custom-image-component


// gatsby-config.js
module.exports = {
  plugins: [
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
            resolve: `gatsby-remark-custom-image-component`,
            options: {
              // plugin options
              componentName: 'image-wrapper',
              imagePropName: 'src',
              sharpMethod: 'fluid',
              // fluid's arguments
              quality: 50,
              maxWidth: 800,

In your markdown:

# src/content/hello-word/index.md
title: Hello World
date: '2015-05-01T22:12:03.284Z'

<image-wrapper src='./hero.jpg'></image-wrapper>

In your custom component:

import React from 'react'

// the result of sharp's image transformation will be passed directly to this component.
// so if you use `fluid` as `sharpMethod`, you'll get
// src, srcSet, base64, aspectRatio, srcSetType, sizes, density, originalImage. 
// Please refer to `gatsby-plugin-sharp` docs.
const ImageWrapper =  ({ src, srcSet }) => <img src={src} srcSet={srcSet} />

export { ImageWrapper }

In your template:

import React from 'react'
import rehypeReact from 'rehype-react'
import { ImageWrapper } from '../components/ImageWrapper'

const renderAst = new rehypeReact({
  createElement: React.createElement,
  components: { 'image-wrapper': ImageWrapper }, // register our component

const BlogPostTemplate = ({ data }) => {
  const post = this.props.data.markdownRemark
  return <div>{ renderAst(post.htmlAst) }</div>

export default BlogPostTemplate

export const pageQuery = graphql`
  query BlogPostBySlug($slug: String!) {
    markdownRemark(fields: { slug: { eq: $slug } }) {


Name Value Note
componentName string, default ‘image-wrapper’ Custom component name, use in markdown
imagePropName string, default ‘src’
sharpMethod string, default ‘fluid’ Sharp method, one of ‘resize’, ‘fluid’ or ‘fixed’

You can also pass in any of the selected sharp method’s arguments. Reference here.

© 2023 Gatsby, Inc.