Elementor Widget
The TableCrafter Data Table widget brings your JSON, CSV, and Google Sheets data into the Elementor editor with visual controls and a true live preview, so you design tables against real data instead of guessing.
Overview
TableCrafter ships a native Elementor widget that wraps the same rendering engine used by the [tablecrafter] shortcode and the Gutenberg block. Instead of typing shortcode attributes, you configure the table through Elementor's standard control panel: a Content tab for data and behavior, and a Style tab for typography, colors, borders, and spacing.
The standout feature is the live data preview. When you drop the widget on the canvas and point it at a data source, the editor fetches a sample of your real data and renders it in place, complete with feature badges showing which interactive tools (search, filters, export, auto-refresh) will appear on the published page.
The widget only loads when Elementor is active. On the frontend it builds a standard [tablecrafter] shortcode under the hood, so every table behaves identically whether placed via Elementor, Gutenberg, or a raw shortcode.
Requirements
- Elementor installed and active. The widget registers on the elementor/loaded hook and is skipped entirely on sites without Elementor.
- Elementor 3.5 or newer uses the modern
elementor/widgets/registerregistration; older versions fall back to the legacyelementor/widgets/widgets_registeredhook automatically. - WordPress 5.0+ and PHP 8.0+ (the plugin minimum as of version 3.5.6).
Adding the Widget
- Edit any page or post with Edit with Elementor.
- In the widget panel search box, type TableCrafter (or browse the dedicated TableCrafter widget category).
- Drag the TableCrafter Data Table widget onto your layout.
- In the Data Source section, choose a Source Type and paste your Data Source URL.
- Adjust display, advanced, and style options. The canvas preview updates as you work.
The widget lives in both the general widgets list and a dedicated TableCrafter category with a table icon, so you can find it quickly even on busy sites with many third-party widgets.
Data Source Controls
This section (Content tab) tells TableCrafter where to read data and which columns to keep.
| Control | Required | Description |
|---|---|---|
| source_type | Required | Select box: API URL / JSON File, Google Sheets, or CSV File. Defaults to API URL. Choosing Google Sheets reveals an inline setup tip. |
| data_source | Required | A URL control holding your JSON API, CSV file, or public Google Sheets link. Supports Elementor dynamic tags. Maps to the shortcode source attribute. |
| root_path | Optional | Dot-path to a nested array in a JSON response (e.g. data.results). Shown only for the API URL source type. Maps to root. |
| include_columns | Optional | Comma-separated list of keys to display. Leave empty to show all. Maps to include. |
| exclude_columns | Optional | Comma-separated list of keys to hide. Maps to exclude. |
For Google Sheets, the widget's inline help suggests the CSV gviz export format: https://docs.google.com/spreadsheets/d/[ID]/gviz/tq?tqx=out:csv. The sheet must be shared so anyone with the link can view it.
Display Options
These switches and fields (Content tab) control which interactive tools render and how rows paginate and sort.
| Control | Default | Description |
|---|---|---|
| enable_search | yes | Toggle the global search box above the table. Maps to search. |
| enable_filters | yes | Toggle automatic column filters (dropdowns, date ranges, number ranges). Maps to filters. |
| enable_export | off | Allow visitors to export the current view as CSV, Excel, or PDF. Maps to export. |
| per_page | 25 | Rows shown per page (1–1000). Set to 0 to disable pagination. Maps to per_page. |
| sort_column | — | Column name to sort by on initial load. |
| sort_order | asc | Ascending or descending. Combined with the sort column into the shortcode sort="column:direction" attribute. Only shown once a sort column is set. |
As of version 3.5.6 the export handler produces a genuine OOXML .xlsx workbook and a structurally valid PDF, so enabling Data Export gives clients real, openable files rather than renamed HTML.
Advanced Features
The Advanced section (Content tab) covers live data refreshing, caching, editor preview behavior, and fallback messaging.
| Control | Default | Description |
|---|---|---|
| auto_refresh | off | Periodically re-fetch data from the source on the frontend. Maps to auto_refresh. |
| refresh_interval | 300 | Seconds between refreshes (30 to 86400). Shown only when auto-refresh is on. Passed to the shortcode refresh_interval (converted to ms by the engine). |
| cache_duration | 15 | Minutes to cache fetched data (0–1440). Set to 0 to disable. Maps to the cache attribute. |
| enable_live_preview | yes | Render live data inside the Elementor editor. Disable if a heavy source slows the editor. |
| preview_rows | 5 | Number of rows to fetch for the editor preview (1–25). Shown only when live preview is enabled. |
| loading_message | "Loading data..." | Text shown while data is being fetched on the frontend. |
| error_message | "Unable to load data. Please try again." | Text shown when a frontend data fetch fails. |
How the Live Preview Works
Live preview is what separates the Elementor widget from a plain shortcode. The mechanics:
- Editor render: Elementor's
content_template()draws a preview shell with a header strip reading "Live Preview", the row count, the host of your source, and badges for each enabled feature (Search, Filters, Export, Auto-refresh). - Data fetch: The bundled
tc-elementor-previewscript reads the widget'sdata-preview-configand POSTs to the tc_elementor_preview AJAX action, secured by thetc_proxy_noncenonce and anedit_postscapability check. - Server processing: The handler fetches and renders your source through TableCrafter's PHP engine, slices it to your Preview Rows value (clamped to 1–25 for editor performance), and returns the sample. Search, filters, export, and pagination are intentionally turned off in the preview so it stays lightweight.
- Caching: The preview script caches a fetched sample in the browser for five minutes per source/root/include/exclude combination, so re-opening the widget panel does not re-hit the source needlessly.
- Refresh: Opening the widget's editor panel (the
panel/open_editor/widget/tablecrafter-data-tableaction) re-initializes the preview so config changes appear without a full reload.
The editor preview is a curated sample: limited rows and no interactive tools. The published page always renders the full dataset with every enabled feature. A footer note in the preview ("Full table with all features will be displayed on the frontend") reinforces this.
When no source is set, the widget shows a placeholder prompting you to configure a data source. If live preview is switched off, it shows a compact summary card listing the source host instead of fetching data.
Styling the Table
The Style tab exposes native Elementor group controls so the table inherits your design system. Available sections:
- Table Styling: typography, background color, border, border radius, and box shadow on the table container.
- Header Styling: header typography, background color, text color, and padding for
<th>cells. - Rows Styling: row background, hover background, text color, cell padding, and row border color for
<td>cells.
All style controls target TableCrafter's .tc-table, .tc-table-container, .tc-table th, and .tc-table td selectors scoped to the widget, so changes never leak to other tables on the page.
Because styling is applied through Elementor selectors rather than inline shortcode attributes, you can reuse Elementor global colors and fonts and keep the table on-brand across templates.
Equivalent Shortcode
On the frontend the widget assembles a standard shortcode from your settings. A widget configured with a JSON API, a nested root path, curated columns, search on, export on, 10 rows per page, and a default sort produces output equivalent to:
[tablecrafter source="https://api.example.com/data.json" root="data.results" include="name,email,date" search="true" filters="true" export="true" per_page="10" sort="name:asc"]This means anything you can express in the widget is portable to a classic theme or template file. To reuse the same table outside Elementor, copy the equivalent shortcode or call it from PHP:
// In a template file
echo do_shortcode('[tablecrafter source="https://api.example.com/data.json" search="true"]');Troubleshooting
- Widget not in the panel: confirm Elementor is active and clear Elementor's CSS/cache from Elementor → Tools → Regenerate CSS. The widget registers on both modern and legacy Elementor hooks for compatibility.
- Preview stuck on "Loading": verify the source URL is reachable and public. The preview uses the same server-side fetch as the frontend, so CORS is not the issue; an unreachable or auth-protected endpoint is the usual cause.
- Preview shows fewer columns than expected: check Include Columns / Exclude Columns — those filters apply to the preview too.
- Editor feels slow on large sources: lower Preview Rows or turn off Enable Live Preview; the frontend table is unaffected.
Next, see shortcodes.html for the full [tablecrafter] attribute reference, or gutenberg-block.html if you are building on a block-based theme instead.