GravityBoard Voting Guide

This guide covers everything you need to know about using voting in GravityBoard, from enabling the feature to managing vote budgets and sorting cards by popularity.

Overview #

Voting lets users upvote and downvote cards on your board. This is useful for:

Prioritizing feature requests: let your team or customers vote on what matters most.
Running polls: collect opinions on ideas or proposals.
Surfacing popular items: the most-voted cards can automatically sort to the top.

Each card displays a vote count with upvote and downvote buttons. You can optionally limit how many votes each user gets (a “vote budget”) and choose how often that budget resets.

Enabling voting #

In the WordPress sidebar, navigate to Forms, click the form you want to edit, then go to Settings and choose GravityBoard.
Edit your board feed or create a new one.
Scroll to the Voting section.
Toggle Enable Voting to on.
Configure the settings below as needed.
Click Save Settings.

Once enabled, vote buttons appear on cards on the board. If Lanes with Voting is configured, only cards in the selected lanes have active vote buttons; cards in other lanes show a disabled widget.

Note: Voting requires a custom database table (gk_entry_votes). GravityBoard creates this table automatically when the feature is first used. If the table cannot be created (for example, due to database permission issues), voting features will not appear on the board and an admin notice will be displayed.

Voting settings #

After you enable voting, additional settings appear:

Upvote Only

When enabled, only the upvote button is shown; the downvote button is hidden. Users can upvote a card or remove their upvote by clicking a dedicated minus button that appears next to the up arrow once they’ve voted. Vote counts on the board will never go negative.

This is ideal for feature request boards, idea voting, and other scenarios where you want positive endorsement without negative voting.

Default: Off

Lanes with Voting

Controls which lanes allow voting. Select one or more lanes from the multi-select dropdown. When specific lanes are selected, only cards in those lanes can be voted on. Cards in other lanes show a disabled vote widget: the vote count is still visible, but the buttons are grayed out. Hovering the widget shows a tooltip reading “Voting is not available in this lane.”

If no lanes are selected, voting is enabled in all lanes.

This is useful when you want voting in early-stage lanes (like “Ideas” or “Under Review”) but not in later lanes (like “In Progress” or “Done”).

Default: No lanes selected (voting enabled everywhere)

Sort Cards by Votes

When enabled, cards within each lane are sorted by vote count, highest first, on page load. Manual drag-and-drop reordering within a lane is disabled while this is active, so the vote-based order is preserved. You can still move cards between lanes.

After votes change during your session, click the Update order button in the board header to re-apply the sort. This keeps the UI stable while you’re voting and lets you review the current order before it shuffles.

Default: Off

Vote Budget Per User

The total number of votes each user can distribute across all cards on this board. For example, if the budget is 10, a user can spread 10 votes across as many or as few cards as they like.

Set to 0 for unlimited votes (no budget restriction). The value must be a non-negative integer.

Default: 0 (unlimited)

Vote Budget Reset Period

How often the vote budget resets. When the period expires, users regain their full budget. All reset boundaries are calculated in UTC, not your site’s local time.

Option	Behavior
Never (all-time budget)	Budget never resets. Once votes are spent, they stay spent unless the user removes them.
Daily	Budget resets each day at 00:00 UTC.
Weekly	Budget resets every Monday at 00:00 UTC (ISO week).
Monthly	Budget resets on the 1st of each month at 00:00 UTC.
Yearly	Budget resets on January 1st at 00:00 UTC.

Default: Never

Best practice: if you want ongoing feedback (like a weekly team standup board), choose a reset period that matches your workflow. If you want cumulative all-time rankings, leave it set to “Never.”

Voting permissions #

Voting permissions are configured in the Permissions tab of your board feed settings, under the Voting Permissions section. These settings only appear when voting is enabled.

Who Can Vote on Cards

Controls which users can upvote and downvote cards. You can select one or more user roles or Gravity Forms capabilities.

Default: Users with the “Edit Entries” Gravity Forms capability (gravityforms_edit_entries).

Who Can See Who Voted

Controls which users can see voter details on cards.

Default: Users with the “Edit Entries” Gravity Forms capability (gravityforms_edit_entries).

Best practice: give voting access to a broad audience (anyone who views the board), but restrict voter visibility to administrators or editors who need that information.

Using voting #

Casting a vote

Each card shows a vote widget with up to three elements:

Up arrow: click to upvote.
Vote count: the net total displayed between the arrows.
Down arrow: click to downvote (hidden when Upvote Only is on).

Click the up arrow to upvote a card. The vote count increases, the up arrow turns green, and your vote is recorded immediately.

Click the down arrow to downvote a card. The vote count decreases, and the down arrow turns red. (Not available in upvote-only mode.)

Stacking votes

Each click of the up arrow adds +1 to your weight on that card; each click of the down arrow adds −1. This means you can throw multiple votes behind the cards you care about most. A user who clicks up three times on the same card has a weight of +3 on it, which costs three votes from their budget (if a budget is configured).

When a board has unlimited voting (no budget) and your stacked weight on a card reaches 2 or more (for example, +3 or −2), a small badge showing the signed total appears below the vote buttons. Single votes (+1 or −1) don’t display a badge.

Removing or reversing a vote

Votes are not toggled. Your weight on a card is always an integer, and to move it back toward 0 you click the opposite arrow:

If your weight is +1 (or higher), click the down arrow to bring it back down. Each down click reduces your weight by 1 and reclaims one vote back into your budget.
If your weight is −1 (or lower), click the up arrow to bring it back up. Each up click adds 1 and reclaims one vote.

Reaching weight 0 returns your votes to your budget, and the vote row is deleted from the database. Continuing past 0 (for example, from +1 straight through to −1) spends budget again.

Example: you upvoted a card (+1) but changed your mind and want to downvote it. Click the down arrow twice. The first click brings you back to 0 (and reclaims the vote you spent), and the second click takes you to −1 (and spends a fresh vote).

In upvote-only mode, the down arrow is hidden. When you’ve upvoted, a small minus (−) button with the accessible label “Remove upvote” appears next to the up arrow; click it to reduce your weight back toward 0 one step at a time.

Understanding your vote budget

When a board has a vote budget, a small budget indicator appears below the vote buttons on every card. It shows the votes you have left compared to your total allowance in the format remaining/total, for example 5/10.

How budget works:

Clicking a button that moves your weight away from 0 (like a first upvote, or a second upvote on a card you’ve already upvoted) spends one vote from your budget.
Clicking a button that moves your weight toward 0 (like clicking down on a card you’ve upvoted) reclaims one vote back to your budget.
When your budget runs out, the buttons that would spend budget become disabled. The buttons that would reclaim budget remain available.
The reclaim direction is always available, even when your budget is exhausted. You can always walk a vote back toward 0.

Unlimited mode: when the budget is set to 0, there is no budget restriction and no budget indicator. Vote as many times as you like on any card.

Who voted on a card

Users with the Who Can See Who Voted permission can view the full voter list on a card, including each voter’s direction and stacked weight. The currently-logged-in user is highlighted with a (You) badge in the list.

Sorting cards by votes #

When Sort Cards by Votes is enabled in board settings:

Cards in each lane are sorted by vote count, highest first.
Cards with the same vote count keep their original order.
Within-lane drag-and-drop reordering is disabled to preserve the vote-based sort order.
Moving cards between lanes still works. You can drag a card from one lane to another. After moving, the card is sorted into the correct position in its new lane based on its vote count.
The sorted order is applied on page load. During a session, use the Update order button in the board header to re-apply the sort after voting.

Best practice: enable vote sorting when you want the board to reflect community priorities automatically. Disable it when manual card ordering is important to your workflow.

GravityView integration #

GravityBoard adds two fields to GravityView that let you display and interact with votes in any GravityView layout (Table, List, DataTables, etc.).

Votes Count field

Displays the total vote count for an entry. Entries that have never been voted on show “—” (em dash). Entries that have been voted on show the numeric count, including 0 if votes have cancelled out.

This field supports sorting. Click the column header in a Table layout to sort by vote count. GravityView sorts numerically, so 18 appears before 9 in descending order.

Under the hood, the field reads from the gravityboard_votes_count entry meta, which is kept in sync with the votes table every time a vote is added or removed.

Entry Voting field

Renders the interactive vote widget (upvote/downvote buttons with count) directly in your GravityView layout. Logged-in users with the appropriate permissions can vote from the View without visiting the board.

Votes cast through the GravityView widget are stored in the same data as the board: a vote from a View is visible on the board the next time it’s loaded, and vice versa. When a vote is cast, GravityView’s entry cache is automatically invalidated so the next page load reflects the new order. Multiple vote widgets on the same page stay in sync; if a board and a View are open in separate browser tabs, reload the other tab to see votes from the first.

Sorting a View by votes

You can set the default sort order of a View to use the Votes Count field:

Edit your View.
Under Filter & Sort, set the sort field to Votes Count.
Choose Descending to show the most-voted entries first.

Table column header sorting also works: clicking the Votes Count header toggles between ascending and descending.

Voted By filter

When GravityView Advanced Filter is active, a Voted By filter is available in the Query Filters settings. This lets you show only entries that the current user has (or has not) voted on.

Setting	Behavior
Voted By: is: Currently Logged-in User	Shows only entries the logged-in user has voted on.
Voted By: is not: Currently Logged-in User	Excludes entries the logged-in user has voted on.

The filter runs as an EXISTS / NOT EXISTS subquery against the votes table, so it stays efficient even with large entry counts.

This is useful for building personalized Views like “My Voted Ideas” or filtering out entries a user has already reviewed.

Notifications #

You can include vote data and voter information in Gravity Forms notifications using merge tags.

Vote data merge tags

Merge tag	Description
`{gravityboard_votes:count}`	Number of distinct users who have voted on the card (one per voter, regardless of stacked weight).
`{gravityboard_votes:average}`	Average weight across all voters, rounded to 2 decimal places. Stacked weights are included.
`{gravityboard_votes:total}`	Net vote total (sum of all weights). Can be negative.
`{gravityboard_votes:up}`	Number of users with a positive total weight on the card. A user at +3 counts as 1.
`{gravityboard_votes:down}`	Number of users with a negative total weight on the card. A user at −2 counts as 1.
`{gravityboard_voters:emails}`	Comma-separated list of voter email addresses.

Legacy `{gv_entry_ratings:*}` aliases

If you previously used the Ratings & Reviews plugin and have notifications that reference its {gv_entry_ratings:*} merge tags, GravityBoard automatically registers these aliases so existing notifications keep working.

These aliases are only active when the Ratings & Reviews plugin is not installed; otherwise, Ratings & Reviews handles the tags itself.

Legacy tag	Maps to
`{gv_entry_ratings:count}`	`{gravityboard_votes:count}`
`{gv_entry_ratings:sum}`	`{gravityboard_votes:total}`
`{gv_entry_ratings:average}`	`{gravityboard_votes:average}`
`{gv_entry_ratings:range}`	Weight range (max weight − min weight) across voters on the card.

Setting up voter notifications

Go to your form’s Notifications settings.
Create or edit a notification.
Use any of the merge tags above in the message body, subject, “To,” “CC,” or “BCC” fields.

Example use cases

Notify voters when a card moves lanes: set up a notification triggered by card lane changes, and include {gravityboard_voters:emails} in the “To” field so everyone who voted is notified of the status change.
Include vote summary in notifications: add {gravityboard_votes:total} and {gravityboard_votes:count} to the notification body so recipients can see how popular a card is.
Include voter list in admin summaries: add {gravityboard_voters:emails} to the notification body so administrators can see who is interested in each card.

Keyboard and accessibility #

Keyboard navigation

Tab to the vote buttons on a card. Disabled buttons are skipped in the tab order.
Enter or Space to cast or remove a vote (standard button behavior).
A visible focus ring outlines the currently-focused button.

Screen reader support

Up and down buttons use aria-pressed so their state is announced as “pressed” or “not pressed.”
Vote count changes are announced automatically via aria-live="polite".
When a budget is active, the budget indicator carries a descriptive label like “5 of 10 votes remaining” and is announced politely when it changes.
Lane-restricted widgets announce “Voting is not available in this lane.”
Vote errors are announced via an alert role.

Visual design

Up and down arrows use distinct icon shapes (pointing up versus pointing down), so the voting direction is recognizable without color.
Active states are indicated through color (green for upvoted, red for downvoted) combined with border and background color changes, not just icon color.
Disabled buttons are dimmed (lower opacity, desaturated) and show a not-allowed cursor.
Vote counts switch to green for positive totals and red for negative totals.

Troubleshooting #

I can’t vote on cards

Check permissions: make sure your user role is included in “Who Can Vote on Cards” in the board’s Permissions settings.
Check your budget: if a budget is configured, you may have used all your votes. Remove a vote from another card to free one up, or wait for the budget to reset.
Log in: voting requires a logged-in WordPress account.

Voting features don’t appear on the board

Voting requires the gk_entry_votes database table. If table creation failed (for example, due to insufficient database privileges), GravityBoard hides the voting UI and displays an admin notice. Check your WordPress admin for the notice, or ask your host to confirm that the database user has CREATE TABLE permission, then reload the board.

I can’t drag cards to reorder them within a lane

This is expected when Sort Cards by Votes is enabled. Cards are automatically sorted by vote count, so manual reordering within a lane is disabled. You can still drag cards between lanes.

To re-enable manual reordering, turn off Sort Cards by Votes in your board settings.

Vote counts don’t seem right

Refresh the page to see the latest vote counts. Vote counts reflect the aggregate of all user votes on a card.

Vote buttons are grayed out on some cards

This is expected when Lanes with Voting is configured. Cards in lanes not included in the list show a disabled vote widget. To allow voting in that lane, add it to the Lanes with Voting setting in your board feed.

Vote counts show “—” in GravityView

The em dash indicates the entry has never been voted on. Once a user casts a vote on that entry, the count will display as a number.

Voted By filter shows no entries

Check login status: the “Currently Logged-in User” filter requires a logged-in user. Logged-out visitors see no results.
Check that you’ve voted: the filter only matches entries where you have an active vote in the votes table.
Check Advanced Filter: the Voted By filter requires the GravityView Advanced Filter extension to be active.

I can’t see who voted on a card

Your user role may not have permission. Ask your board administrator to check the Who Can See Who Voted setting in the board’s Permissions tab.

Budget didn’t reset when I expected

Budget resets are calculated in UTC, not your local time. For example, a “Daily” reset happens at 00:00 UTC, which may be several hours before or after midnight in your timezone. Check the Vote Budget Reset Period table above for the exact boundaries.