gatsby-image: difference between childImageSharp vs imageSharp

Great question, Sharp is an amazing tool and can do so much with any JavaScript application. It also has extensive documentation its self I suggested looking in to.http://sharp.dimens.io/en/stable/

First imageSharp can be used in a variety of ways especially with the Transform. But here is an simple example of just utilizing imageSharp in the Gatsby universe. Imagine this is index.js in the pages folder and there is route of home

import { Home } from 'routes/Home/Home'

/* eslint no-undef: "off" */
export const pageQuery = graphql`
  query HomeQuery {
    image1Image: imageSharp(id: { regex: "/image1.png/" }) {
      sizes(quality: 100) {
        ...GatsbyImageSharpSizes_withWebp
      }
    }
    image2Image: imageSharp(id: { regex: "/image2.png/" }) {
      sizes(quality: 100) {
        ...GatsbyImageSharpSizes_withWebp
      }
    }
    image3Image: imageSharp(id: { regex: "/image3.png/" }) {
      sizes(quality: 100) {
        ...GatsbyImageSharpSizes_withWebp
      }
    }
}
`
export default Home

Then a childImageSharp you would use this for defining image styles throughout an application, for instance you have a folder called types the path would be src/types/images.js for example in this file you would define the resolution and size of the image and the datasets associated. Then export childImageSharp as you plan to reuse the child over and over in different parts of your app.

// @flow

export type GatsbyImageResolutions = {
    resolutions: {
        base64?: string,
        height: number,
        src: string,
        srcSet: string,
        width: number,
    },
};

export type GatsbyImageSizes = {
    sizes: {
        aspectRatio: number,
        base64?: string,
        sizes: string,
        src: string,
        srcSet: string,
    },
};

export type Image = {
    childImageSharp: GatsbyImageResolutions | GatsbyImageSizes,
};

Now here is an example of the power of transforming an image. This example is a returned with a ImageURL via the WordPress REST-api to a standard href=link to a link. Well Resizing and reshaping the image with childIamgeSharp! Both existing in one file src/post/post.js

/**
     * Transform internal absolute link to relative.
     * 
     * @param {string} string The HTML to run link replacemnt on
     */
    linkReplace(string) {
        // console.log(string)
        const formatted = string.replace(
            /(href="https?:\/\/dev-your-image-api\.pantheonsite\.io\/)/g,
            `href="/`
        )

        return formatted
    }

    render() {
        const post = { ...this.props.data.wordpressPost }
        const headshot = { ...this.props.data.file.childImageSharp.resolutions }
        const { percentScrolled } = { ...this.state }
        const contentFormatted = this.linkReplace(post.content)

        return (
            <div ref={el => (this.post = el)}>
                <div className={styles.progressBarWrapper}>
                    <div
                        style={{ width: `${percentScrolled}%` }}
                        className={styles.progressBar}
                    />
                </div>

                <div className={styles.post}>
                    <h1
                        className={styles.title}
                        dangerouslySetInnerHTML={{ __html: post.title }}
                    />

                    <div
                        className={styles.content}
                        dangerouslySetInnerHTML={{ __html: contentFormatted }}
                    />

                    <Bio headshot={headshot} horizontal={true} />
                </div>
            </div>
        )
    }
}

Post.propTypes = {
    data: PropTypes.object.isRequired,
}

export default Post

export const postQuery = graphql`
    query currentPostQuery($id: String!) {
        wordpressPost(id: { eq: $id }) {
            wordpress_id
            title
            content
            slug
        }
        file(relativePath: { eq: "your-image-headshot.jpg" }) {
            childImageSharp {
                resolutions(width: 300, height: 300) {
                    ...GatsbyImageSharpResolutions
                }
            }
        }
    }

Let me know if this helps you,If not I would be glad to help explain in more detail. As Sharp and Gatsby are both subjects I am very Passionate about and I deal with Sharp almost daily in my full-time Job.


It's been a while since this question was asked, but I hope to give a direct answer to the question 'what's the different between imageSharp and childImageSharp':

Different between imageSharp & childImageSharp

They are always the same type of node, which is ImageSharp. The difference is the reference point.

In a typical gatsby blog, all files will be first processed with gatsby-transformer-file-system. Each file will get a node with information such as what type of file it is, then, a plugin like gatsby-transformer-sharp will pick up the node with the relevant type/extension, then process it further and create a new node:

File                                image.png

                                        |

                                   create a node with
gatsby-transformer-file-system ->  "type": "File",
                                   "extension": "png"

                                        |

                                   whenever see a node 
                                   with a valid image extension,
gatsby-transformer-sharp       ->  create a node with
                                   "type": "ImageSharp"
                                   that contains info of images
                                   processed by `gatsby-plugin-sharp`

Whenever this happens, a parent-child relationship is created between the original File node and the ImageSharp node. The child ImageSharp node will be queriable on the File node with the name childImageSharp.


File                                ImageSharp
  |--id: 1                              |--id: 2
  |--children                           |--parent
  |     `--[ id: 2 ]                    |    `--id: 1
  `--childImageSharp                    |--fluid
        |--id: 2                       ...
        |--fluid
       ...

It means you can query the same ImageSharp node in at least 2 ways:

1. From the File node

ImageSharp node doesn't contain any info about its location in the file system, so if you want to get an image from folder src/X, you'd need to query it like:

query {
  // relativePath is relative to the folder set in `gatsby-transformer-file-system`
  file ( relativePath: { eq: "src/X"} ) {
    childImageSharp {
      id
      fluid {
        src
      }
    }
  }
}

2.Directly get the ImageSharp

Perhaps somehow you know the exact id of the ImageSharp node. You can get it by:

{
  imageSharp (id: {eq: "2"}) { // not a real id
    id
    fluid {
      src
    }
  }
}

You can also query multiple images from allFile, or allImageSharp.

This will return with an error:

// error
{
  childImageSharp {
    id
  }
}

Other plugins share the same kind of relationship as well. You can also find a childMardownRemark node on the File type, that resolve to a MarkdownRemark node.

It doesn't have anything to do with gatsby-image -- it's just different way to resolve to the same node.

Tags:

Gatsby