Render images from caisy

This guide will walk you through the process of fetching assets from caisy and rendering them in your web application.

With your caisy project you have a GraphQL API that allows you to fetch assets. You can use the following queries to fetch assets:

To get the latest 10 published assets from your project, use the following query:

query allAssets {
  allAsset(first: 10) {
    edges {
      node {
        id
        title
        description
        src
        width
        height
        originType
        blurHash
        dominantColor
      }
    }
  }
}

To get a single asset by its id, use the following query:

{
  Asset(id: "0852be87-1707-4c06-8920-2b2ebcec953c") {
    id
    src
    width
    height
  }
}

The src attribute is the most important as it provides the direct URL to the image. Other attributes provide additional information that can be helpful. For instance, the description attribute can be used as an alt tag for the images, and the width and height attributes can be useful for maintaining the aspect ratio of the image when resizing.

Once you have fetched the assets, you can render them using the image component provided by your framework or any other image component. One such component is unpic-img, a framework-agnostic image component that can be used in many frameworks and automatically detects the caisy src URL.

These image components transform the src you pass down and some further information like width and height into a resized src URL. For example, the following URL:

https://assets.caisy.io/assets/24f83c2f-4d07-4666-84ca-420f9ab91dec/519eb852-8fd2-4b31-8dcc-1c2217f71b7f/db8c2d70-e1a0-44c7-a4c7-a1e3c85cf261b8552817fb18469ca06cc1b7da705c37dold1955.jpg

Can be transformed to:

https://assets.caisy.io/assets/24f83c2f-4d07-4666-84ca-420f9ab91dec/519eb852-8fd2-4b31-8dcc-1c2217f71b7f/db8c2d70-e1a0-44c7-a4c7-a1e3c85cf261b8552817fb18469ca06cc1b7da705c37dold1955.jpg?width=640

If your browser window is smaller than 640px and you render the image full screen.

caisy automatically detects if your browser supports webp and transforms the images automatically so you do not have to worry about that.

If you prefer to use the native img component, you can do so with modern standards like async loading. Here is an example:

<img
   style={`background-color: ${dominantColor}`}
   loading="lazy"
   src={`${src}?w=960&h=960`}
   srcset={`${src}?w=960&h=960 1920w, ${src}?w=640&h=640 1280w, ${src}?w=640&h=640 640w, ${src}?w=480&h=480 480w, ${src}?w=320&h=320 320w`}
   alt={description ?? ''}
/>

In this example, we also use the provided dominantColor as background. In addition to the dominantColor, caisy also calculates and exposes the blurHash of images for you. You can learn more about blurHash here.

Whether you choose to use the image component provided by your framework or a third-party component like unpic-img, the process remains the same. With caisy, you have the flexibility to choose the method that best suits your needs.

Rendering images on the web is not just about displaying them. It's about optimizing the user experience, improving page load times, and ensuring the images look good on all devices. Here are some best practices for rendering images on the web:

Use Responsive Images

Responsive images are images that work well on devices with widely differing screen sizes, resolutions, and other such features. They are important for the overall performance of your website, and they ensure that your images look good on all devices.

In the context of caisy, the srcset attribute in the img tag is used to provide different image sources for different screen sizes. The browser will choose the most suitable source based on the current layout of the page, the screen size, and the resolution of the screen.

Use Lazy Loading

Lazy loading is a strategy to identify resources as non-blocking (or non-critical) and load these only when needed. It's a way to shorten the length of the critical rendering path, which translates into reduced page load times.

With caisy, you can use the loading="lazy" attribute in the img tag to defer loading offscreen images until they're needed.

Use Modern Image Formats

Modern image formats like WebP or AVIF offer superior compression and quality characteristics compared to older formats like JPEG or PNG. Using these formats can result in significant bandwidth savings and improved rendering speed.

caisy automatically detects if your browser supports WebP and transforms the images automatically, so you don't have to worry about that.

Use a Placeholder

A placeholder can improve the user experience by displaying a blurred preview of the image while the actual image is loading. This can be achieved using the blurHash provided by caisy.

Conclusion

Rendering images on the web involves more than just displaying them. By following these best practices, you can ensure that your images load quickly and look good on all devices, leading to an improved user experience and potentially better SEO rankings. With caisy, implementing these best practices is straightforward and easy, allowing you to focus on creating engaging content for your users.

Projects created after the 23rd of August 2023 have this feature enabled by default. For older projects, it can be enabled by navigating to the Asset System blueprint and accessing the settings of the src file field, while check marking it in the advanced options of the field.
This feature allows users to set a specific focal point on assets. If an image is cropped to a specific, non-original aspect ratio, this focal point will then be interpreted. Example of the caisy UI:

Example asset URL you receive from the external API that has a focal point set:
...pexelsrachelvine2114206.jpg?focal_point=44.85,25.56

This URL, as it stands, will not do any cropping. The parameters of the focal point become valuable if you actually do cropping.
Example of a wide landscape image:
...pexelsrachelvine2114206.jpg?focal_point=44.85,25.56&width=1000&height=400
Example of cropping for an upright cut image:
...pexelsrachelvine2114206.jpg?focal_point=44.85,25.56&width=400&height=700

This allows editors to use this focal point feature on there images, while the developers have zero effort to support this in there frontend.