When working with Advanced Custom Fields (ACF) in WordPress, you might encounter situations where you need to customize the order of field values beyond the default alphabetical sorting.
By default, when retrieving multiple selections from an ACF checkbox or multi-select field, the values are typically displayed in their original order. However, there are scenarios where you might need a specific item to always appear first, regardless of the selection order or alphabetical sorting.
The Solution
We can leverage WordPress’s filter system along with ACF’s hooks to intercept and modify the field values before they’re displayed. Here’s a professional implementation that can be adapted for any ACF field:
/**
* Customizes the order of ACF field values
*
* @param mixed $value The field value
* @param integer $post_id The post ID where the value was loaded from
* @param array $field The field array containing all settings
* @return mixed The modified field value
*/
add_filter('acf/load_value/name=your_field_name', 'customize_acf_field_order', 10, 3);
function customize_acf_field_order($value, $post_id, $field) {
// Return early if no value or not an array
if (empty($value) || !is_array($value)) {
return $value;
}
// Custom sorting function
usort($value, function($a, $b) {
// Define your priority item
$priority_item = 'Priority Item';
// Priority item always comes first
if ($a === $priority_item) return -1;
if ($b === $priority_item) return 1;
// Optional: Add additional sorting logic here
// return strcmp($a, $b); // Uncomment for alphabetical sorting of other items
// Keep original order for other items
return 0;
});
return $value;
}
How It Works
The Filter Hook: We use ACF’s acf/load_value filter, which allows us to intercept the field value before it’s returned to the template.
Early Return: The function first checks if we have a valid array to work with, preventing unnecessary processing.
Custom Sorting: The usort function is used with a custom comparison function that:
Always places the priority item first
Maintains the original order for other items
Can be extended to include additional sorting logic
Error Prevention: The code includes proper error checking and maintains data integrity throughout the sorting process.
Implementation Example
Here’s a real-world example showing how to always display “Symphony” first in a list of musical genres:
add_filter('acf/load_value/name=music_genres', 'order_music_genres', 10, 3);
function order_music_genres($value, $post_id, $field) {
if (empty($value) || !is_array($value)) {
return $value;
}
usort($value, function($a, $b) {
if ($a === 'Symphony') return -1;
if ($b === 'Symphony') return 1;
return 0;
});
return $value;
}
// Usage in template:
<?php
$genres = get_field('music_genres');
if ($genres): ?>
<ul class="genre-list">
<?php foreach ($genres as $genre): ?>
<li><?php echo esc_html($genre); ?></li>
<?php endforeach; ?>
</ul>
<?php endif; ?>
Advanced Customization
You can extend this solution to handle more complex sorting requirements:
1 – Multiple Priority Items:
$priority_order = ['Symphony', 'Opera', 'Chamber'];
return array_search($a, $priority_order) - array_search($b, $priority_order);
1 – Conditional Sorting:
if ($field['type'] === 'checkbox') {
// Custom sorting for checkbox fields
} else {
// Different sorting for other field types
}
Best Practices
- Always add the filter to your theme’s functions.php or a custom plugin, not in the template files.
- Use meaningful function names that describe their purpose.
- Include proper error checking and validation.
- Document your code, especially if working in a team environment.
- Consider performance implications when working with large datasets.
Compatibility and Performance
This solution works with:
- All recent versions of ACF (including PRO)
- Various field types (checkbox, select, etc.)
- Different return formats (value, label, array)
- WordPress multisite installations
The performance impact is minimal as the sorting operation is performed only when the field is loaded.
This professional approach to customizing ACF field order provides a robust, maintainable solution that can be adapted to various use cases. It maintains code quality standards while solving a common development challenge in a clean and efficient way.
Remember to always test thoroughly in a development environment before implementing in production, especially when modifying core functionality of your WordPress site.
