Voxel Location Radius Field
The {CODICTS} Voxel Location Radius Field plugin extends the Voxel Theme by adding a new Location Radius field type and matching search filter. It allows post authors to define a geographic location with a configurable radius — ideal for delivery zones, service areas, coverage regions, and any use case where a location needs an associated range. Visitors can then search for posts whose radius covers their location.
Requirements
Important: This plugin requires a Voxel child theme to be active. The plugin installs modified template files into the child theme to enable its functionality. If no child theme is detected, the plugin will display an admin notice and will not load.
Installation & Activation
Start by downloading the plugin from the Downloads page on your dashboard on the CoDicts website.
After downloading, install and activate the plugin in WordPress by navigating to “Plugins” > “Add New” > “Upload Plugin” and selecting the downloaded zip file. Click “Install Now” and then “Activate”.
On activation, the plugin automatically installs required template files into your active Voxel child theme. No settings page is needed — the plugin adds a new field type and filter type directly into the Voxel system.
Note: When you deactivate or uninstall the plugin, the template files are automatically removed from your child theme. If you switch to a different child theme, the files are cleaned up from the old theme automatically.
What This Plugin Solves
Voxel’s built-in location field stores an address with latitude/longitude coordinates, but it doesn’t support defining a radius around that location. Businesses like restaurants with delivery zones, service providers with coverage areas, or venues with reach zones need to specify not just where they are, but how far their service extends.
This plugin adds that missing piece — a location field with a radius slider, plus a search filter that finds posts whose defined radius covers the visitor’s location.
Key Features
| Feature | Description |
|---|---|
| Location + Radius Field | Address autocomplete with a configurable radius slider (min, max, step, units). |
| Reverse Radius Search | Visitors search by entering their location — the filter finds posts whose stored radius covers that location. |
| Visual Radius on Maps | Semi-transparent colored circle drawn on the map representing the service/delivery area. |
| Multi-Map Support | Works with Google Maps, Mapbox GL JS, and OpenStreetMap (Leaflet). |
| Kilometers & Miles | Choose between km and mi for each field independently. |
| Dynamic Data Tags | Use address, lat, lng, radius, and distance values in Voxel templates. |
| Customizable Radius Color | Color picker in the Map widget or PHP filter hook for programmatic control. |
Adding a Location Radius Field to a Post Type
Step 1: Open the Post Type Editor
In the WordPress admin, go to Voxel → Post Types and select the post type you want to add the field to (e.g., “Restaurants”, “Services”).
Step 2: Add the Field
In the Fields tab, click “Add Field”. Look for “{C} Location Radius” in the field type list and add it.
Step 3: Configure the Field
Click on the newly added field to expand its settings:
| Setting | Default | Description |
|---|---|---|
| Label | {C} Location Radius | The field label shown to users on the create/edit post form. |
| Key | — | The field slug used internally (e.g., delivery_area). |
| Placeholder | — | Placeholder text for the address input. |
| Radius Label | Delivery Radius | Label shown above the radius slider. |
| Radius Description | — | Optional description text below the radius label. |
| Radius Default | 10 | Starting value of the radius slider. |
| Radius Units | km | Kilometers (km) or Miles (mi). |
| Radius Min | 0 | Minimum slider value. |
| Radius Max | 100 | Maximum slider value. |
| Radius Step | 1 | Slider increment (supports decimals). |
| Required | Off | Whether this field must be filled in to submit the post. |
Step 4: Save the Post Type
Click “Save Changes” on the post type. The Location Radius field is now available on the create/edit post form for this post type.
How Authors Use the Field
When a post author creates or edits a post with a Location Radius field, they see:
1. Address Input — An autocomplete address field. The author types an address and selects from suggestions, or clicks “Use my current location”.
2. Map Picker (Optional) — A “Pick on the map” toggle that opens an interactive map where the author can click to set or adjust the pin location.
3. Radius Slider — A smooth slider to set the radius value. The slider respects the min, max, step, and units you configured.
When the map picker is open, a semi-transparent colored circle is drawn around the marker, visually representing the radius. As the author adjusts the slider, the circle updates in real time and the map auto-zooms to fit.
Adding the Search Filter
To let visitors search for posts whose radius covers their location, add the Location Radius search filter.
Step 1: Open the Post Type Filters
In Voxel → Post Types → [Your Post Type], go to the Search Filters (or Templates) section where you configure filters for the search form widget.
Step 2: Add the Filter
Add a new filter and select “{C} Location Radius” as the filter type.
Step 3: Configure the Filter
| Setting | Description |
|---|---|
| Label | The filter label shown on the search form. |
| Placeholder | Placeholder text for the address input. |
| Source | Select the Location Radius field this filter queries against. |
| Radius Units | km or mi (should match the field’s units). |
| Icon | Icon displayed on the filter in the search form. |
Step 4: Re-Index the Post Type
After adding the filter, you must re-index the post type for the spatial data to be created. Go to Voxel → Post Types → [Your Post Type] → Index and click “Re-index”.
Important: Re-indexing is required after adding or changing the Location Radius filter. Without it, the search will return no results.
How the Search Works
The Location Radius filter performs a “reverse radius” search — the opposite of a typical proximity search:
| Traditional Proximity Search | This Plugin’s Reverse Radius Search |
|---|---|
| Visitor enters their location + a radius → finds posts within that radius | Visitor enters their location → finds posts whose stored radius covers the visitor’s location |
For example, if a restaurant has set a 15 km delivery radius and a visitor searches from an address 10 km away, that restaurant will appear in the results. If the visitor is 20 km away, it won’t.
The search uses the Haversine formula for accurate great-circle distance calculations, accounting for the Earth’s curvature.
Visitors can enter their address, use their current location, or use the “Visible map area” option on the search form.
The {C} Map (VX) Widget
The plugin automatically enhances the Voxel Map Elementor widget (renamed to “{C} Map (VX)”) with radius circle support. This happens through the template override — no manual setup is required.
Radius Circles on the Map
When viewing a single post on a map, the post’s radius is drawn as a semi-transparent colored circle around its marker.
When viewing search results on a map, each result post that has a Location Radius field displays its own radius circle.
Customizing the Radius Color
In the Elementor editor, select the Map widget and look for the “{C} Radius Settings” section in the Content tab. Use the color picker to set the radius circle color.
The default color is dark red (#AA0000).
For developers: You can also set the color programmatically using a PHP filter:
add_filter('codicts_voxel_location_radius_field::radius_color', function($color) {
return '#00FF00'; // Green radius circles
});Note: The PHP filter takes priority over the Elementor color picker setting.
Supported Map Providers
The plugin works with all three map providers available in the Voxel Theme:
| Provider | Radius Circle | Auto-Zoom |
|---|---|---|
| Google Maps | Circle overlay that follows the marker position automatically. | Fits map bounds to the circle. |
| Mapbox GL JS | Circle layer that scales correctly across zoom levels. | Fits map bounds with padding. |
| OpenStreetMap (Leaflet) | Leaflet circle with configurable styling. | Fits map bounds with padding. |
The plugin automatically detects which map provider you have configured in Voxel and uses the appropriate rendering method.
Dynamic Data Tags
The Location Radius field exposes the following dynamic data tags for use in Voxel templates and Elementor dynamic tags:
| Tag | Example Output | Description |
|---|---|---|
address | 123 Main St, New York, NY 10001 | Full geocoded address. |
short_address | 123 Main St | First part of the address (before first comma). |
medium_address | 123 Main St, New York | First two parts of the address. |
long_address | 123 Main St, New York, NY | All but the last part (typically excludes the country). |
lat | 40.74844 | Latitude coordinate. |
lng | -73.98565 | Longitude coordinate. |
radius | 15 km | Radius value with unit. |
Distance Tags
When used with a “Nearby” order in a Voxel post feed, the following distance tags become available:
| Tag | Example Output | Description |
|---|---|---|
distance.meters | 5432 | Distance from the search point in meters. |
distance.kilometers | 5.432 | Distance in kilometers. |
distance.miles | 3.375 | Distance in miles. |
Note: Distance tags require a “Nearby” order on the post feed to function, as they depend on a reference search point.
Common Use Cases
| Use Case | Field Label Example | Typical Radius Range |
|---|---|---|
| Restaurant delivery zones | Delivery Radius | 1–30 km |
| Service provider coverage | Service Area | 5–100 km |
| Freelancer travel willingness | Willing to Travel | 10–200 km |
| Event venue reach | Event Coverage | 5–50 km |
| Utility service zones | Coverage Zone | 1–500 km |
Troubleshooting
“Voxel Theme Not Detected” or “Voxel Child Theme Not Detected” Error
Ensure the Voxel Theme is installed and that a Voxel child theme is set as the active theme — not the parent Voxel theme directly. Go to Appearance → Themes and verify your active theme shows “Parent: Voxel”.
Field Not Appearing in the Post Type Editor
Make sure the plugin is activated and the template files were installed correctly. Try deactivating and reactivating the plugin to force a template reinstall. Clear any object cache (Redis, Memcached) if you use one.
Search Returns No Results
The most common cause is a missing re-index. After adding the Location Radius filter to a post type, you must re-index: go to Voxel → Post Types → [Your Post Type] → Index and click “Re-index”. Also verify that the search location is actually within the radius of at least one post, and that the filter’s Source is set to the correct Location Radius field key.
Radius Circle Not Showing on the Map
The map widget should automatically be the enhanced {C} Map (VX) version via the template override. Check the browser console for JavaScript errors. Verify the post has a Location Radius field with a valid radius value (not 0 or empty). For Mapbox, the circle is drawn after the map fully loads — give it a moment.
Radius Color Not Changing
Check the {C} Radius Settings section in the Elementor Map widget settings. If you are using the PHP filter hook, it takes priority over the Elementor setting. Make sure the filter returns a valid hex color string like #00FF00.
Radius Slider Not Appearing
The slider uses the noUiSlider library bundled with Voxel. If Voxel’s assets aren’t loading correctly, the slider won’t appear. Check the browser console for “noUiSlider is not defined” errors.
Templates Not Updating After Plugin Update
The plugin automatically checks and updates templates on every page load. If templates aren’t updating, try deactivating the plugin, manually deleting the template files from your child theme, and then reactivating.
Plugin Breaks After a Voxel Theme Update
Major Voxel theme updates can change internal template structures. Check for a plugin update from CoDicts after updating Voxel. If issues persist, deactivate the plugin temporarily until a compatible version is released.
For further support, visit codicts.com or contact us at support@codicts.com.