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.