How to Implement Text Wrap Around Images in Sanity CMS: A Step-by-Step Guide

Introduction

One of the most frustrating limitations content editors face when working with Sanity CMS is the inability to naturally wrap text around images. While platforms like WordPress and Webflow offer this functionality out of the box, Sanity's structured content approach requires a custom solution to achieve this fundamental layout technique.

Text wrapping (or floating images) is essential for creating visually appealing, readable content that integrates images naturally with your text. Without it, content can feel rigid and disconnected, with images either stacked between paragraphs or taking up the full width of the content area.

In this tutorial, we'll solve this problem by building a custom wrapTextAroundImage component for Sanity that gives your content editors the power to float images to the left or right of text, control image width, and maintain a clean reading experience.

By the end of this tutorial, you'll be able to:

• Create a custom schema component in Sanity Studio
• Configure image positioning controls for content editors
• Implement the frontend rendering component
• Integrate the solution with your existing Portable Text setup
• Offer your content team a more flexible, professional publishing experience

Prerequisites

• A working Sanity CMS project
• Basic knowledge of React and TypeScript
• Familiarity with Sanity schemas and Portable Text
• Next.js application setup for frontend rendering

Solution Overview

Our solution involves creating a custom Portable Text block type in Sanity that combines an image with associated content, along with controls for positioning and width. This component will:

1. Allow content editors to select an image from their media library
2. Provide options to float the image left or right
3. Control the image width as a percentage of the container
4. Add caption and alt text for accessibility
5. Include a content field where editors can write text that will wrap around the image

Example component input:

Example 1 component output:

(The following text and image come from A Tale of Cities.)

"It was the best of times, it was the worst of times, it was the age of wisdom, it was the age of foolishness, it was the epoch of belief, it was the epoch of incredulity, it was the season of Light, it was the season of Darkness, it was the spring of hope, it was the winter of despair, we had everything before us, we had nothing before us, we were all going direct to Heaven, we were all going direct the other way--in short, the period was so far like the present period that some of its noisiest authorities insisted on its being received, for good or for evil, in the superlative degree of comparison only."

Example 2 component output:

(The following text and image come from The White Darkness piece, written in The New Yorker Magazine in 2018. A user on StackOverflow asked how he could recreate this specific figure with Sanity CMS.)

"In 2012, Worsley launched a new expedition, to mark the centennial of the race between Amundsen and Scott to the South Pole. Gow and Adams, who had married and settled down with families, declined to go, and so Worsley drew recruits from the military. He and a partner, Lou Rudd, followed the trail of Amundsen and raced against another party, which took the route of Scott. Once more, Worsley proved an extraordinary commander—Rudd called him a “true inspiration”—and they won the nine-hundred-mile contest, which raised nearly three hundred thousand dollars for a Royal British Legion fund that assists wounded soldiers."

The implementation leverages Sanity's Portable Text for structured content handling while adding custom controls for the visual presentation. On the frontend, we'll use CSS floats with appropriate margins to create the text wrapping effect.

This approach is superior to alternatives like using fixed-position components or grid-based layouts because it:

• Preserves the natural flow of content
• Adapts responsively to different screen sizes
• Maintains proper document structure for accessibility
• Gives content editors direct control over presentation

The Challenge

Sanity CMS is built around the concept of structured content, which separates content from presentation. While this provides excellent flexibility and reusability, it can make certain common layout patterns challenging to implement.

By default, Sanity's Portable Text editor treats images as block-level elements that occupy the full width of their container. This creates a disconnected experience where text appears either above or below images, rather than flowing around them.

Content editors coming from traditional WYSIWYG editors expect the ability to position images within text—a fundamental layout capability that enhances readability and visual appeal. Without this option, content can feel clunky and overly structured.

The technical challenges we need to overcome include:

1. Creating a custom block type that combines image and content fields
2. Providing intuitive controls for image position and width
3. Ensuring proper rendering on the frontend using CSS floats
4. Maintaining proper text flow and whitespace around the image
5. Ensuring the solution works responsively across device sizes

Step-by-Step Implementation

Let's break down the implementation process into manageable steps:

Step 1: Creating the Schema Definition

First, we need to define our custom wrapTextAroundImage schema in Sanity. This will form the foundation of our component.

1// schemas/objects/wrapTextAroundImage.ts
2
3export const wrapTextAroundImage = {
4  name: 'wrapTextAroundImage',
5  title: 'Wrap Text Around Image',
6  type: 'object',
7  fields: [
8    {
9      name: 'image',
10      title: 'Image',
11      type: 'image',
12      options: {
13        hotspot: true,
14      },
15      fields: [
16        {
17          name: 'alt',
18          title: 'Alternative Text',
19          type: 'string',
20          description: 'Important for accessibility and SEO',
21        },
22        {
23          name: 'caption',
24          title: 'Caption',
25          type: 'string',
26          description: 'Optional caption to display below the image',
27        },
28      ],
29    },
30    {
31      name: 'position',
32      title: 'Position',
33      type: 'string',
34      options: {
35        list: [
36          { title: 'Left', value: 'left' },
37          { title: 'Right', value: 'right' },
38        ],
39        layout: 'radio',
40      },
41      initialValue: 'left',
42    },
43    {
44      name: 'width',
45      title: 'Width (%)',
46      type: 'number',
47      description: 'Width of the image as percentage of container',
48      validation: (Rule) => Rule.min(10).max(60),
49      initialValue: 30,
50    },
51    {
52      name: 'content',
53      title: 'Content',
54      type: 'array',
55      of: [{ type: 'block' }],
56      description: 'Text that will wrap around the image',
57    },
58  ],
59  preview: {
60    select: {
61      image: 'image',
62      position: 'position',
63      width: 'width',
64    },
65    prepare({ image, position, width }) {
66      return {
67        title: 'Text with Wrapped Image',
68        subtitle: `Position: ${position || 'left'}, Width: ${width || 30}%`,
69        media: image,
70      };
71    },
72  },
73};

This schema creates a complex object that includes:

• An image field with support for hotspot positioning, alt text, and captions
• A position field with radio button options for left or right alignment
• A width field that accepts a percentage value with validation
• A content field that uses Portable Text for rich text editing

The preview configuration ensures that the component is easily identifiable in the Sanity Studio interface, showing a thumbnail of the selected image and the positioning details.

Step 2: Integrating with Document Schemas

Next, we need to integrate our new component with existing document schemas so that it's available to content editors.

1// schemas/documents/post.ts
2
3export const post = {
4  name: 'post',
5  title: 'Blog Post',
6  type: 'document',
7  fields: [
8    // ... existing fields like title, slug, etc.
9    {
10      name: 'content',
11      title: 'Content',
12      type: 'array',
13      of: [
14        { type: 'block' },
15        { type: 'image' },
16        // Add our new component to the available block types
17        { type: 'wrapTextAroundImage' }
18      ],
19    },
20  ],
21  // ... rest of schema
22};

Step 3: Building the Frontend Renderer

Now we need to create the frontend component that will render our custom block type. This is where the magic happens, transforming the structured content into a visually appealing layout.

Based on the code you provided, let's build out a complete implementation:

1// components/PortableText.tsx
2
3import {
4  type PortableTextComponents,
5  PortableText as SanityPortableText,
6} from '@portabletext/react';
7import { PortableTextObject } from 'sanity';
8
9import { cn } from '@kit/ui/utils';
10
11import { SanityImage } from './SanityImage';
12
13export function PortableText({ value }) {
14  const components = {
15    types: {
16      wrapTextAroundImage: ({ value }) => {
17        const { image, position = 'left', width = 30, content } = value;
18        const floatClass = 'left'
19            ? 'float-left mr-6'
20            : 'float-right ml-6';
21        return (
22          <div className="clear-both">
23            <figure
24              className={cn(floatClass, 'relative mb-4')}
25              style={{ width: `${width}%` }}
26            >
27              <SanityImage image={image} />
28              {image.caption && (
29                <figcaption className="mt-2 text-center text-sm">
30                  {image.caption}
31                </figcaption>
32              )}
33            </figure>
34            <PortableText value={content} />
35          </div>
36        );
37      },
38      // ... other custom components
39    },
40    // ... mark components, list components, etc.
41  };
42
43  return (
44    <div className="prose">
45      <SanityPortableText components={components} value={value} />
46    </div>
47  );
48}

This component:

1. Takes a Portable Text value and renders it using @portabletext/react
2. Includes a custom renderer for our wrapTextAroundImage block type
3. Extracts the image, position, width, and content from the block value
4. Applies appropriate CSS classes for floating the image left or right
5. Sets the width of the image as a percentage using inline styles
6. Renders the caption if one was provided
7. Recursively renders the content field using the same PortableText component

The CSS classes float-left and float-right are used to create the text wrapping effect, while the margins (mr-6 and ml-6) ensure there's adequate spacing between the image and the text.

Step 4: Testing and Fine-tuning

After implementing the component, it's essential to test it thoroughly in various scenarios. Let's check for:

1. Responsive behavior: How does the component behave on different screen sizes?
2. Content overflow: What happens with very short or very long content?
3. Image sizing: How do different width percentages affect the layout?
4. Accessibility: Is the content still accessible with screen readers?

Based on testing, we might need to add additional CSS to handle edge cases:

1/* styles/components/portableText.css */
2
3/* Clear floats at the end of content sections to prevent layout issues */
4.portable-text-content::after {
5  content: "";
6  display: table;
7  clear: both;
8}
9
10/* Responsive adjustments for small screens */
11@media (max-width: 640px) {
12  .portable-text-content figure.float-left,
13  .portable-text-content figure.float-right {
14    float: none;
15    width: 100% !important;
16    margin-left: 0;
17    margin-right: 0;
18  }
19}

Final Result

After implementing all the steps, content editors can now:

1. Insert the "Wrap Text Around Image" component in their content
2. Upload or select an image from the media library
3. Choose whether the image should float left or right
4. Adjust the image width to balance with the surrounding text
5. Add a caption and alt text for accessibility
6. Write content that will naturally flow around the image

The end result is a more professional, magazine-like layout that improves readability and visual interest; Text wraps nicely around the image, providing a natural reading flow while integrating visual elements directly with the content.

Complete Application Structure

1├─ schemas/
2│  ├─ documents/
3│  │  └─ post.ts
4│  ├─ objects/
5│  │  └─ wrapTextAroundImage.ts
6│  └─ index.ts
7├─ components/
8│  ├─ PortableText.tsx
9│  └─ SanityImage.tsx
10├─ styles/
11│  └─ components/
12│     └─ portableText.css
13└─ pages/
14   └─ [...slug].tsx

Conclusion

In this tutorial, we've successfully implemented a custom component in Sanity CMS that allows content editors to wrap text around images — a fundamental layout capability that's missing from Sanity's default toolkit.

By creating a specialized block type with intuitive controls for positioning and width, we've significantly enhanced the content editing experience. The solution provides:

• A natural way to integrate images with text
• Control over image positioning and sizing
• Support for captions and alt text
• Responsive behavior across different screen sizes

This implementation demonstrates how Sanity's flexibility allows you to extend its capabilities to match the expectations of content editors coming from traditional WYSIWYG editors, without sacrificing the benefits of structured content.

Next Steps

To build on this implementation, consider:

• Adding more positioning options (center with text wrap, full-width)
• Implementing margin controls for fine-tuning spacing
• Creating variant components for special cases (like pull quotes)
• Expanding the content editor's toolkit with similar custom components for other layout patterns

Additional Resources

• Sanity Documentation on Custom Components
• Next.js Image Component Documentation
• CSS Floats and Positioning
• GROQ Query Language for Content Selection