Skip to main content

​
Overview

Actions describe what happens when a user interacts with an element. They represent the semantic intent, not the technical implementation. 
<button data-wcp="action:add">Add to Cart</button>

​
Core Actions

Purpose: Links to a new page or section Use cases:
  • Menu items
  • Product links
  • Breadcrumbs
  • “Learn More” buttons
Example: 
<a href="/products" data-wcp="action:navigate; effect:navigate">
  View All Products
</a>
Combine with effect:navigate for full page loads or effect:modal for in-page navigation

​
submit

Purpose: Submits form data or saves information Use cases:
  • Form submissions
  • Settings updates
  • Profile changes
  • Data entry
Example: 
<form data-wcp="action:submit; effect:async; target:#notification">
  <input type="email" name="email" />
  <button type="submit" 
          data-wcp="action:submit; effect:async; primary:true">
    Save Email
  </button>
</form>

​
add

Purpose: Adds an item to a collection Use cases:
  • Add to cart
  • Add to wishlist
  • Add to playlist
  • Create new item
Example: 
<button data-wcp="action:add; effect:async; target:#cart">
  Add to Cart
</button>
Usually paired with effect:async since adding to a collection typically doesn’t navigate away

​
remove

Purpose: Removes an item from a collection Use cases:
  • Remove from cart
  • Delete item
  • Remove from list
  • Unsubscribe
Example: 
<button data-wcp="action:remove; effect:async; target:#cart-items">
  Remove Item
</button>
Purpose: Performs a search or query Use cases:
  • Search bars
  • Query interfaces
  • Lookup tools
Example: 
<form data-wcp="action:search; effect:async; target:#results">
  <input type="search" name="q" placeholder="Search..." />
  <button data-wcp="action:search; effect:async; primary:true">
    Search
  </button>
</form>

​
filter

Purpose: Filters or narrows down content Use cases:
  • Category filters
  • Sort options
  • Faceted search
  • Content refinement
Example: 
<button data-wcp="action:filter; effect:async; target:#products"
        data-category="electronics">
  Electronics
</button>

​
auth

Purpose: Authentication-related actions Use cases:
  • Login
  • Signup
  • Logout
  • Password reset
Example: 
<form data-wcp="action:auth; effect:navigate">
  <input type="email" name="email" />
  <input type="password" name="password" />
  <button type="submit" 
          data-wcp="action:auth; effect:navigate; primary:true">
    Log In
  </button>
</form>

​
purchase

Purpose: Initiates a payment or checkout flow Use cases:
  • Checkout buttons
  • Buy now
  • Payment submission
  • Order placement
Example: 
<button data-wcp="action:purchase; effect:navigate; primary:true">
  Proceed to Checkout
</button>
Use action:purchase for payment initiation. Use action:submit for the final payment form submission.

​
Custom Actions

For domain-specific workflows, use the custom. namespace: 
<!-- SaaS Platform -->
<button data-wcp="action:custom.deploy; effect:async">
  Deploy to Production
</button>

<!-- Healthcare App -->
<button data-wcp="action:custom.prescribe; effect:modal">
  Prescribe Medication
</button>

<!-- Financial Platform -->
<button data-wcp="action:custom.transfer; effect:modal">
  Transfer Funds
</button>
Namespace convention: 
action:custom.{your-action-name}
Document custom actions in your API or developer documentation for AI agent builders

​
Choosing the Right Action

  • Product page: action:add (add to cart), action:purchase (buy now)
  • Cart page: action:remove (remove item), action:purchase (checkout)
  • Checkout: action:submit (payment form), action:auth (sign in)
  • Search: action:search (search bar)
  • Filters: action:filter (categories, tags)
  • Navigation: action:navigate (article links, pagination)
  • Settings: action:submit (save changes)
  • Data actions: action:add (create), action:remove (delete)
  • Navigation: action:navigate (between sections)
  • Primary submit: action:submit; primary:true
  • Cancel: action:navigate
  • Delete/Remove: action:remove

​
Best Practices

Use Semantic Actions

Choose actions that describe intent, not implementation. action:add not action:click-button

Combine with Effects

Always pair actions with effects to describe complete behavior

Mark Primary Actions

Use primary:true for the main action in each context

Custom When Needed

Use custom namespace for domain-specific actions not covered by core vocabulary

​
Next Steps

Learn Effects

How elements behave

Learn Regions

Semantic page zones

View Examples

Real-world usage