All documentation
Reference
Shortcode reference
Every parameter the [gravity_table] shortcode accepts, with examples.
The [gravity_table] shortcode is the primary integration surface. Every Pro feature has a corresponding shortcode parameter.
Required parameter#
id#
The numeric ID of a saved table (visible in Tables → All Tables).
[gravity_table id="42"]Display parameters#
include#
Comma-separated list of field labels or IDs to display as columns. Overrides the saved table config for this shortcode invocation.
[gravity_table id="42" include="name,email,plan,status"]exclude#
Inverse of include, every column except these.
[gravity_table id="42" exclude="internal_notes,debug_field"]sort#
Initial sort: column:direction (direction is asc or desc).
[gravity_table id="42" sort="created:desc"]per_page#
Rows per page. Defaults to 25.
[gravity_table id="42" per_page="10"]mobile_layout#
Either cards (default at ≤480px) or table (force table everywhere).
[gravity_table id="42" mobile_layout="cards"]Filtering#
filter_user_owns#
Names a column whose value is matched against the logged-in user (id, login, or email, auto-detected from column type). Each visitor sees only the rows they own. Higher-privilege roles (administrator by default) bypass this gate.
[gravity_table id="42" filter_user_owns="customer_id"]filter_by_user#
Legacy alias for filter_user_owns="user_id", kept for backwards compatibility, but prefer filter_user_owns in new shortcodes (it’s explicit about which column carries the owner).
[gravity_table id="42" filter_by_user="true"]filters#
Comma-separated list of column names that appear as filter UI (date range, multi-select, search, etc).
[gravity_table id="42" filters="status,plan,created"]filter#
Hard-coded filter applied at render time. Format: column:value. Multiple values via | (OR), multiple columns via , (AND).
[gravity_table id="42" filter="status:active|trial,plan:pro"]search_field#
Comma-separated list of columns the global search box searches. Default: every visible column. Restrict for cleaner results when some columns shouldn’t match (internal_notes, ids, etc.).
[gravity_table id="42" search_field="name,email,sku"]Permissions#
allowed_roles#
Comma-separated list of WordPress roles that can view the table. * allows any logged-in user; empty allows guests.
[gravity_table id="42" allowed_roles="customer,subscriber"]require_login#
"true" hides the table entirely from logged-out users (no log-in prompt either).
[gravity_table id="42" allowed_roles="customer" require_login="true"]allow_edit#
Comma-separated list of columns users can edit inline. See Permissions.
[gravity_table id="42" allow_edit="phone,email,address"]edit_permissions#
Per-column edit gates. Format: column:capability,column:capability.
[gravity_table id="42" allow_edit="status,priority,notes" edit_permissions="status:manager,priority:manager"]audit_log#
"true" enables the audit-log table for every edit.
[gravity_table id="42" allow_edit="status,notes" audit_log="true"]Bulk + Add Entry#
bulk#
Comma-separated list of bulk actions: approve, delete, export, plus any custom actions registered via PHP hooks.
[gravity_table id="42" bulk="approve,export,delete"]bulk_permissions#
Per-action capability gates.
[gravity_table id="42" bulk="approve,delete" bulk_permissions="delete:manage_options"]allow_add#
"true" shows the Add New Entry button (renders the form in a Thickbox modal).
[gravity_table id="42" allow_add="true"]add_permissions#
Capability required to see the Add Entry button.
[gravity_table id="42" allow_add="true" add_permissions="manage_options"]Export#
export#
Comma-separated list of export formats: csv, excel, pdf. See Exports.
[gravity_table id="42" export="csv,excel,pdf"]export_permissions#
Per-format gates.
[gravity_table id="42" export="csv,pdf" export_permissions="excel:manager"]audit_exports#
"true" logs every export with format, row count, filter state, and file hash.
[gravity_table id="42" export="csv,pdf" audit_exports="true"]Auto-refresh#
auto_refresh#
"true" polls the database on a fixed interval and re-renders the table.
[gravity_table id="42" auto_refresh="true" refresh_interval="30"]refresh_interval#
Polling interval in seconds. Defaults to 60.
refresh_indicator#
"true" shows a small spinning glyph while a refresh is in flight.
Totals#
totals#
Comma-separated list of numeric columns to sum in the footer row. Recalculates as filters narrow the table.
[gravity_table id="42" totals="amount,quantity"]Aggregations & Top-N (4.2.x)#
group_by#
Roll up rows by one or more columns. Exposes virtual aggregate columns: _count, _sum_<col>, _avg_<col>, _min_<col>, _max_<col> for use in columns and totals.
[gravity_table id="42"
group_by="status,owner"
columns="status,owner,_count,_sum_value"
totals="_sum_value"]top_n_count#
Cap the table at the top N rows by a chosen column, server-side. Applied before pagination, search, and export, so all those operations respect the slice.
[gravity_table id="42"
top_n_count="10"
top_n_column="value"
top_n_direction="desc"]top_n_column#
Which numeric column ranks the top-N. Required if top_n_count is set.
top_n_direction#
asc for bottom-N, desc for top-N. Default: desc.
Responsive (4.2.55)#
responsive_mode#
cards (default, one card per row below the breakpoint), scroll (horizontal scroll on narrow viewports), or flip (first column becomes a persistent row label, other columns flow inline next to their header).
[gravity_table id="42" responsive_mode="flip"]flip_breakpoint#
Pixel width below which flip mode kicks in. Default 768.
[gravity_table id="42" responsive_mode="flip" flip_breakpoint="600"]interactive#
"false" renders the table fully server-side with no client-side JS bundle. Lose: inline editing, live polling. Keep: search, sort, filter via standard form submission. Useful for SEO-critical pages where every kilobyte counts.
[gravity_table id="42" interactive="false"]Putting it all together#
A production customer-portal shortcode using the modern parameters:
[gravity_table id="customer-orders"
filter_user_owns="customer_id"
allowed_roles="customer,subscriber,administrator"
columns="created,product,amount,status,shipping_address,phone"
allow_edit="shipping_address,phone,delivery_notes"
edit_permissions="status:manager"
bulk="export"
export="csv,pdf"
audit_log="true"
totals="amount"
responsive_mode="flip"]For deeper walkthroughs, see the guides.
[gravity_chart] shortcode (4.1.23+)#
A separate top-level shortcode that renders bar / donut SVG charts and number tiles from the same data the table reads. Server-rendered, zero JavaScript runtime, no charting library dependency.
id#
Same as [gravity_table], the Gravity Form id.
type#
bar (default), donut, or number (single big number for stat strips).
aggregate#
count (default), sum, avg, min, or max.
value#
Numeric column the aggregation operates on. Required for all aggregates except count.
group_by#
Column whose unique values become the chart’s groups (one bar per value, one donut wedge per value). Not used for type="number".
filter#
Same syntax as the table shortcode. Narrow the chart to a subset (e.g. status:paid).
allowed_roles, filter_user_owns#
Same semantics as the table shortcode. Charts respect the same permission gates.
height#
Chart height in pixels. Default: 320 for bar/donut, auto for number tiles.
label#
Caption shown under the chart (or the big-number, for type="number").
[gravity_chart id="orders"
type="bar"
group_by="category"
aggregate="sum"
value="total"
filter="status:paid"
height="320"
label="Revenue by category, paid orders"]See the analytics-dashboard guide for full patterns.
[gravity_map] shortcode (4.1.26+)#
Leaflet markers from form entries with lat/lng fields. OpenStreetMap tiles, no API key required.
id#
Same as the table, the Gravity Form id.
lat_field#
Numeric field that holds latitude. Required.
lng_field#
Numeric field that holds longitude. Required.
popup_field#
Optional column whose value renders in the marker’s popup tooltip.
zoom#
Initial zoom level (1-19). Default: auto-fit-to-markers.
height#
Map height in pixels. Default: 480.
filter, allowed_roles, filter_user_owns#
Same semantics as the table, markers respect the same permission gates.
[gravity_map id="properties"
lat_field="lat"
lng_field="lng"
popup_field="title"
zoom="11"
height="480"
filter="status:active"]See the charts-and-maps release post for design rationale.