Overview

The Cortex plugin adds AI capabilities to three types of ACF fields:

  • Text fields: Single-line text inputs
  • Textarea fields: Multi-line text areas
  • WYSIWYG fields: Rich text editors (TinyMCE)

All six text transformation actions are available in ACF fields, just like in the Block Editor. The integration works on:

  • Post and page edit screens
  • Custom post type edit screens
  • ACF Options pages

Accessing AI Controls

AI controls appear automatically in supported ACF fields when you’re editing content. The location of the Edit with AI button depends on the field type:

Text Fields

  1. Look for the sparkles icon – A small icon button appears next to the text input field
  2. Click the icon – This opens the AI action menu
  3. Select an action – Choose from Rewrite, Expand, Condense, Summarise, or Change Tone

The icon button is positioned to the right of the text input, making it easy to access without interfering with your typing.

Textarea Fields

  1. Find the sparkles icon – Located in the top-right corner of the textarea container
  2. Click the icon – Opens the AI action menu
  3. Choose your action – All six actions are available

The button is positioned above the textarea, ensuring it’s always visible even when the field is scrolled.

WYSIWYG Fields

  1. Look for the “Edit with AI” button – A button with text and icon appears in the media buttons area (above the editor toolbar) or before the editor
  2. Click the button – Opens the AI action menu
  3. Select an action – All actions work with rich text content

For WYSIWYG fields, the button placement depends on your ACF field configuration. It may appear:

  • In the media buttons row (alongside “Add Media” and “Add Form”)
  • Above the editor toolbar in a dedicated wrapper

Available Text Actions

All six text transformation actions are available in ACF fields, identical to the Block Editor:

Rewrite

Best for: Improving clarity, fixing grammar, or refining existing text

Rewrites your field content while maintaining its core meaning. Works especially well for:

  • Product descriptions
  • Custom meta fields
  • Options page content
  • Any text that needs polishing

Expand

Best for: Adding detail to brief field content

Takes short text and expands it with relevant details. Useful for:

  • Brief product descriptions that need more detail
  • Short summaries that need elaboration
  • Field values that are too concise

Condense

Best for: Making long field content more concise

Shortens text while preserving key information. Ideal for:

  • Long descriptions that need to fit character limits
  • Verbose content that needs tightening
  • Creating shorter versions of existing text

Summarise

Best for: Creating brief overviews from detailed content

Distills content to essential elements. Perfect for:

  • Creating excerpts from full descriptions
  • Generating summaries for meta fields
  • Extracting key points from longer text

Change Tone

The Change Tone option opens a submenu with two choices:

Professional

  • Converts casual text to formal, business-appropriate tone
  • Perfect for professional descriptions, company information, or formal content

Personal

  • Transforms formal text into friendly, conversational tone
  • Great for user-facing content, blog descriptions, or engaging copy

Using Context Awareness

Context awareness in ACF fields works similarly to the Block Editor but with important differences. When enabled, the AI receives information from your entire page to make more informed transformations.

Enabling Context

  1. Click the Edit with AI button in any ACF field
  2. Check “Include page context” – This checkbox appears at the top of the action menu
  3. Select your action – Choose Rewrite, Expand, Condense, etc.

When context is enabled, the AI receives:

  • Post metadata: Title, excerpt, categories, and tags (if editing a post)
  • All ACF fields: Content from all other text, textarea, and WYSIWYG fields on the same page

This comprehensive context helps the AI:

  • Maintain consistency across all your custom fields
  • Reference information from related fields
  • Generate suggestions that align with your overall content
  • Avoid contradictions between fields

Context Details

What’s included:

  • Post title and excerpt (if available)
  • Categories and tags (if editing a post)
  • All other ACF text, textarea, and WYSIWYG fields on the page
  • Field names are included to help the AI understand context

What’s excluded:

  • The current field being edited (to avoid circular references)
  • Fields longer than 500 characters (truncated with “…”)
  • Non-text field types (images, select fields, etc.)

Limitations:

  • Context extraction has a 5-second timeout
  • If extraction fails, the action proceeds without context
  • Large pages with many fields may take longer to process

When to Use Context

Use context when:

  • Your ACF fields are related to each other
  • You want consistency across multiple fields
  • The field you’re editing should reference other fields
  • You need the AI to understand the full page context

Skip context when:

  • You’re working on a standalone field
  • You want a quick, isolated transformation
  • Context might make suggestions too generic
  • You’re editing fields that aren’t related to each other

The context toggle setting is saved per user in your browser (same setting as Block Editor), so your preference persists across sessions.

Differences from Block Editor

While ACF fields offer the same AI capabilities as the Block Editor, there are some key differences:

Button Placement

  • Block Editor: Edit with AI button appears in the block toolbar
  • ACF Fields: Icon button appears next to or above the field, depending on field type

Field Types

  • Block Editor: Only paragraph blocks support AI
  • ACF Fields: Text, textarea, and WYSIWYG fields all support AI

Context Extraction

  • Block Editor: Extracts up to 100 blocks of content
  • ACF Fields: Extracts all ACF text/textarea/WYSIWYG fields on the page

Editor Integration

  • Block Editor: Native React integration with WordPress editor
  • ACF Fields: Works with ACF’s field system and TinyMCE (for WYSIWYG)

Visual Style

  • Block Editor: Uses WordPress component styling
  • ACF Fields: Custom styling that matches ACF’s interface

The AI Processing Flow

The processing flow in ACF fields is identical to the Block Editor:

1. Processing State

A modal window appears showing:

  • The action being performed (e.g., “Rewriting…”, “Expanding…”)
  • A loading spinner
  • “Processing…” message

The modal cannot be closed during processing. This typically takes 2-10 seconds depending on:

  • The length of your text
  • Whether context is enabled
  • Your selected AI provider
  • Current API response times

2. Success State

Once processing completes, the modal shows:

  • AI Suggestion: The transformed text in a scrollable preview area
  • Discard button: Reject the suggestion and return to your original text
  • Apply button: Accept the suggestion and replace your field content

Review the suggestion carefully:

  • Read through the entire transformed text
  • Check that it matches your intent
  • Verify accuracy and tone
  • Ensure it fits with other fields on the page

3. Error State

If something goes wrong, you’ll see:

  • An error message explaining what happened
  • A Close button to dismiss the modal

Common errors include:

  • API key issues (check your settings)
  • Network connectivity problems
  • Rate limiting (too many requests)
  • Invalid content or context

Applying and Discarding Suggestions

Applying a Suggestion

  1. Review the suggestion in the modal preview
  2. Click “Apply” – This replaces your field content with the AI-generated text
  3. The modal closes automatically
  4. Your field is updated – You can continue editing or make further changes

After applying:

  • The field value is updated immediately
  • ACF’s change detection is triggered
  • You can edit the AI-generated text manually
  • You can apply another transformation
  • You can undo the change using browser undo (Ctrl+Z / Cmd+Z)

Discarding a Suggestion

  1. Click “Discard” – This closes the modal without making changes
  2. Your original text remains unchanged
  3. You can try again with a different action or settings

Discarding doesn’t affect your original content. You can:

  • Try the same action again
  • Try a different action
  • Adjust context settings
  • Make manual edits instead

Best Practices

Getting Better Results

  1. Start with clear, complete content – AI works best with well-formed input
  2. Use context for related fields – Enable context when fields connect to each other
  3. Try multiple actions – If one doesn’t work, experiment with others
  4. Combine AI with manual editing – Use AI as a starting point, then refine manually
  5. Review before applying – Always check suggestions for accuracy and appropriateness

Common Workflows

Refining product descriptions:

  1. Write your initial product description in an ACF field
  2. Select the field and use “Rewrite” with context enabled
  3. Review and apply suggestions
  4. Make final manual adjustments

Expanding brief content:

  1. Enter key points or bullet points in a textarea field
  2. Use “Expand” to add detail
  3. Review for relevance and accuracy
  4. Apply and refine

Creating consistent content:

  1. Fill in multiple related ACF fields
  2. Enable context for all transformations
  3. Use AI to ensure consistency across fields
  4. Review all fields together for coherence

Tone adjustment:

  1. Write your content in your natural voice
  2. Select fields that need tone changes
  3. Use “Change Tone” → Professional or Personal
  4. Review to ensure the tone matches your brand
  5. Apply and make final tweaks

Troubleshooting

Edit with AI button Not Appearing

  • Check ACF is active: Ensure Advanced Custom Fields plugin is installed and activated
  • Verify field type: AI controls only appear in text, textarea, and WYSIWYG fields
  • Check API keys: Ensure at least one provider is configured in settings
  • Refresh the page: Reload if you just added API keys
  • Check screen: AI features work on post edit screens and ACF options pages

Poor Quality Suggestions

  • Try different actions: Some actions work better for specific content
  • Enable/disable context: Context can help or hinder depending on the situation
  • Check your brand voice: Ensure brand voice settings align with your goals
  • Review stop words: Make sure stop words aren’t blocking important terms

Processing Takes Too Long

  • Check your internet connection: Slow connections delay API responses
  • Reduce context: Disable context for faster processing
  • Try a different provider: Some providers may be faster than others
  • Check API status: Provider APIs may be experiencing issues

Errors During Processing

  • Verify API keys: Check that keys are valid and have sufficient credits
  • Check network: Ensure your site can reach AI provider APIs
  • Review error message: The modal will show specific error details
  • Try again: Some errors are temporary and resolve on retry

Context Not Working

  • Check field types: Only text, textarea, and WYSIWYG fields are included in context
  • Verify post metadata: Context extraction requires WordPress editor data
  • Check timeout: Context extraction has a 5-second limit
  • Review console: Browser console may show context extraction warnings

Next Steps

Now that you’re comfortable with AI in ACF fields:

ACF fields are a powerful way to structure custom content, and AI integration makes it even easier to create high-quality, consistent content across all your custom fields.