Definition

The List Widget in Zenphi Dashboards is designed to present data from your tables in a clean, vertically stacked list format—ideal for showcasing items, records, or highlights where clarity and visual simplicity are key. Unlike the Grid Widget, which displays records in a traditional table layout with rows and columns, the List Widget focuses on readability by showing selected fields in a card-style or list-style layout, one record after another.

Each item in the list represents a record from your chosen data source and includes selected fields you define. You can control how many records appear, which fields are shown, and whether users can add, edit, or delete data directly from the dashboard.

Moreover, the List Widget supports interactive features like:

• Action buttons (e.g., to trigger a flow or open a detail page),
• Sorting and filtering (based on data values or viewer identity),
• And custom appearance options that ensure consistency with your dashboard’s design.

It’s especially useful for creating clean record summaries, top-item highlights, task or request listings, and any layout where row-based tabular views might feel overwhelming.

Whether you're building a personal to-do tracker, a customer request list, or a status report board—List Widget offers clarity, simplicity, and actionable interactivity in one flexible component.

Example Use Cases

Below are some real-world examples where the List Widget can enhance visibility, control, and user interaction in a Zenphi dashboard:

---

1. Team Task Overview (for Individual Users)

Display each team member's assigned tasks in a clean, scrollable list. By using filters tied to the current user’s email, each person sees only their tasks—prioritized and sortable by due date or urgency.

---

2. Pending Approvals by Role

Show a list of pending approval requests where only managers or authorized approvers can see and act on them. With dynamic filters, only those with approval permissions will see relevant entries, and can approve or reject right from the list.

---

3. Recent Submissions Log

Show the last 10 submissions (forms, requests, feedbacks, etc.) made by users or customers. This is useful for audit trails, service logs, or customer support follow-ups, with a clean and compact card format.

---

4. Support Tickets Tracker

Display the most recent support tickets submitted by users, with status, issue summary, and contact info. Add actions like “Assign to me” (via Run Flow) or “View Details” (via Detail Page) to handle issues quickly.

---

5. Top Performing Sales Leads

Show a list of the top 5 sales leads by value, sorted descending. Each card displays key info like deal size, owner, and expected close date, helping sales managers prioritize attention.

---

6. Employee Onboarding List

For HR dashboards, show a list of employees currently in onboarding. Each item can link to a detail page showing onboarding progress, start date, mentor assignment, and more.

---

7. Inventory Reorder Alerts

List products that are below restock threshold, allowing warehouse staff or managers to take quick action via integrated flows like "Create Purchase Order".

---

8. Upcoming Events or Deadlines

Display time-sensitive entries like upcoming events, campaign deadlines, or project milestones. Use filtering by date and sorting to keep only the nearest or most urgent on top.

⚙️ Configuration

Setting up the List Widget allows you to fully tailor what data is displayed and how users can interact with it. Whether you're building a read-only list or an interactive tool for managing records, the configuration options provide fine-grained control over data source, visibility, and editing behavior.

🔹 Data Source

The first step in configuring a List Widget is selecting your data source—a Zenphi Table that contains the records you want to display. This is the backbone of the widget. All fields, filters, and actions you define will reference and act upon this selected table.

You’ll be able to choose from any of your existing Zenphi Tables, ensuring consistent access to up-to-date, structured data directly within the dashboard environment.

---

🔹 Fields to Show

Once the data source is selected, you define which columns (fields) you want to display for each record in the list. These fields will appear in the form of a vertically stacked card or line item, depending on your dashboard layout.

• You can add as many or as few fields as needed—from just a couple of key values (like name and status), to a full view of all record details.
• You can reorder the fields to prioritize the most relevant data for users.
• Each record in the list will display these selected fields in the specified order.

This selective field display helps reduce clutter and ensures that viewers see only the information that matters most to the context of your dashboard.

---

🔹 Editing Options

The List Widget supports in-place record management, offering three checkboxes that activate different editing capabilities directly within the dashboard:

1. Add (+)

   • Enabling this option places a “+” icon at the top of the widget.
   • Clicking the "+" allows users to add a new record to the table using the associated form.
   • This is ideal for dashboards used as task input tools, request creation forms, or list-building utilities.

2. Edit

   • Displays an Edit option in the three-dot menu next to each list item.
   • Clicking this opens a form with the record’s current values for modification.
   • This is especially useful for updating statuses, correcting entries, or maintaining clean data from the dashboard itself.

3. Delete

   • Adds a Delete option in the same three-dot menu beside each record.
   • When clicked, the selected record is removed from the table, with appropriate confirmation if configured.

These editing options allow you to control whether the List Widget acts as a read-only view or a fully interactive CRUD (Create, Read, Update, Delete) interface. Enable only the functions that align with your use case and access control needs.

✨

Note: Editing options respect user permissions tied to the table. Users without write access will not be able to modify data even if these options are enabled.

---

🧩 Action Buttons

The List Widget not only displays records in a compact and readable format, but it also allows you to attach interactive actions to each item via a three-dot menu. These action buttons are highly useful when you want users to trigger workflows or navigate to detailed views based on specific records—without leaving the dashboard context.

There are two main types of action buttons you can configure:

---

🔹 1. Run Flow

You can add a Run Flow action to each record, allowing users to trigger a Zenphi flow directly from the list. These flows must use the Table Action trigger in order to appear in the configuration list.

Once configured, the Run Flow option will be displayed in the three-dot menu next to each record. When clicked, the flow will run using the data from that specific record—enabling record-level automation at the user’s fingertips.

✅ Example Use Cases for Run Flow in List Widget:

1. Approval WorkflowA manager views a list of time-off requests in the List Widget. Each item includes a “Send for Approval” button that triggers a flow to route the request for multi-level approval.

2. Issue ResolutionA support agent sees open tickets and clicks “Escalate to Engineering” which triggers a flow to notify the engineering team and assign a task.

3. Auto-Generate PDFFrom a list of employee onboarding forms, clicking “Generate Contract” on a record runs a flow that pulls that user’s data and produces a PDF offer letter or agreement.

---

🔹 2. Detail Page

If you’ve previously designed a Detail Page within your dashboard configuration, you can link it as an action button to each item in the List Widget.

This lets users view or interact with full details of the selected record in a more spacious and structured format than the main list. Detail pages are ideal for presenting complex or extended information that doesn’t fit in a compact card view.

✅ Example Use Cases for Detail Page in List Widget:

1. Project OverviewClicking “View Details” on a project item opens a detail page showing all milestones, timelines, and notes associated with that project.

2. Employee Profile ViewerIn an HR dashboard, clicking a list item for an employee opens a detailed profile view with job history, feedback, and personal information.

3. Purchase Order BreakdownFrom a list of orders, clicking “View Order” opens a breakdown of items, prices, shipment tracking, and invoice documents.

---

Each action can be configured with a custom label and icon color to help users easily identify what the button does. You can assign multiple actions per list item (e.g., both "Run Flow" and "View Details")—making each record a powerful point of interaction.

🔗

For more information on configuring Action Buttons, including flow setup and linking to Detail Pages, refer to the official Zenphi documentation:Action Buttons in Zenphi Dashboards

🎨 Appearance

The List Widget is designed not only for functional clarity but also for visual flexibility. It gives you control over how information is presented in the dashboard, allowing you to tailor the display to your layout, audience, and use case. Here’s how each option works:

---

🔲 Widget Border & Layout

Show Widget Border? This setting determines whether the widget appears as a distinct section with a visible border or as a seamlessly integrated element on the page.

• Enabled: The List Widget is wrapped in a bordered card-like section, visually distinguishing it from other elements on the dashboard.
• Disabled: The widget blends naturally into the dashboard layout, great for minimalist design or embedded-style dashboards.

This gives you layout flexibility—perfect for either clean dashboards with no visual clutter or more structured, modular dashboards with boxed sections.

---

🏷️ Widget Title

Show Widget Title? You can choose to display or hide the title of the widget that appears at the top.

• Enabled: Displays the custom title you've entered (e.g., “Pending Requests” or “My Open Tasks”).
• Disabled: Hides the title for a more compact view or to fit design preferences.

This is especially useful when embedding the List Widget among multiple widgets, where contextual titles may or may not be necessary.

---

🔢 Number of Values (Maximum Cards)

Number of ValuesThis setting controls how many items or cards are shown in the List Widget at any given time.

For example:

• Set to 5 to show only the 5 most recent or top priority items (depending on your sorting/filtering).
• Set to 1 to highlight a single featured item, such as the latest issue reported, or your top-performing salesperson.
• Set a high number to show all items that meet your filter conditions.

This ensures you can limit clutter and control the user experience while still showing the most important data.

---

⚙️ Action Button Customization

When configuring Run Flow or Detail Page buttons (as discussed in the previous section), you can define for each:

• A custom label/title (e.g., “Approve”, “View Record”, “Generate Report”)
• A distinct button color, allowing you to visually distinguish different actions quickly.

With this flexibility, you can:

• Highlight primary actions (e.g., “Send Offer”) in green
• Mark secondary ones (e.g., “View Details”) in blue
• Or draw attention to critical actions (e.g., “Escalate”) in red

This improves user experience and decision-making by providing visual cues and clear calls to action directly within each record’s card.

---

🔍 Filter Conditions & Sort

To ensure your List Widget only displays the most relevant and meaningful data, Zenphi provides powerful built-in filtering and sorting options. These features let you tailor what data appears, to whom, and in what order.

---

📌 Filter Conditions

The Filter Conditions section allows you to define logical rules that determine which records from your data source (table) should be shown in the widget. You can combine AND / OR logic to build complex filtering rules as needed.

🛠️ How It Works:

1. Field SelectionChoose any column from your selected data table.

2. Condition TypeSelect a condition operator. Available options include:

   • equals
   • not equal to
   • contains
   • not contains
   • starts with
   • ends with
   • has none of
   • is null
   • is not null

3. Value InputYou can either:

   • Enter a static value (e.g., "Pending", "Approved")
   • Use the Token Picker to insert dynamic values related to the current user (e.g., user ID, email, role, department, or any custom attributes).

🧠 Dynamic Filtering with Token Picker:

This is especially helpful for personalizing the widget per viewer. For example, if you want each user to see only their own records:

• Example Filter:

  • Field: Assigned To
  • Condition: equals
  • Value: {{CurrentUser.Email}}

This ensures users only see data tied to their email—ideal for dashboards where visibility must be scoped by role, ownership, or team.

✅ Example Use Cases:

1. Show only open support tickets

   • Field: Status
   • Condition: equals
   • Value: Open

2. Show only items assigned to the logged-in user

   • Field: AssignedTo
   • Condition: equals
   • Value: {{CurrentUser.Email}}

3. Show approvals awaiting action by managers

   • Field: Role
   • Condition: equals
   • Value: {{CurrentUser.Attributes.isManager}}
   • (assuming isManager is a custom attribute)

These examples ensure the dashboard is role-aware and displays context-specific data based on the person viewing it.

---

🔃 Sort Conditions

Once your data is filtered, the Sort section lets you define the order in which records appear.

🛠️ How It Works:

• Select one or more columns to sort by.

• For each, choose:

  • Ascending (A → Z or 0 → 9)
  • Descending (Z → A or 9 → 0)

You can apply multi-level sorting, where data is sorted first by one field and then by another if values match.

✅ Example Sorting Scenarios:

1. Sort tasks by priority (highest first)

   • Field: Priority
   • Order: Descending

2. Sort deals by expected close date

   • Field: Close Date
   • Order: Ascending

3. Sort documents by creation date, newest first

   • Field: Created At
   • Order: Descending

---

📌 Example Scenario: Team Task Overview for Individual Users

Objective: Build a personalized task list where each team member sees only their own active tasks, with options to edit, complete, or view more details—all from a single dashboard card interface.

---

🔧 Configuration Breakdown

✅ Data Source

Use the “Team Tasks” table, which contains fields like:

• Task Title
• Description
• Status
• Assigned To (email)
• Due Date
• Priority

---

✅ Fields to Show

Select and arrange the following fields to display on each task card:

• Task Title (highlighted)
• Priority (to the left)
• Due Date (as a secondary line)
• Status (at the bottom)

---

✅ Editing Options

Enable all three:

• Add (for new task creation via the ➕ icon)
• Edit and Delete (visible under the 3-dot menu on each card)

---

✅ Action Buttons

• Run Flow: "Mark as Complete" Configured to update the task's status when clicked.
• Detail Page: "Task Details" Opens a pre-configured page showing task notes, history, and file attachments.

---

✅ Filter Conditions

Apply a filter to show only tasks where:

• Assigned To equals {{current_user.email}}
• Status is not equal to "Completed"

This ensures each user only sees their active, in-progress tasks.

---

✅ Sort

Sort the list by:

• Due Date (ascending)
• Then by Priority (descending)

So tasks that are urgent and closer to their deadline rise to the top.

---

✅ Number of Values

Set to 5, so only the top five tasks are shown at a time—prioritized and manageable.

---

🎨 Appearance Settings

• Enable Show Widget Border and Title: Widget is clearly boxed with the title “My Tasks”.
• Configure Run Flow action to appear in blue with label “✔ Mark Complete”.
• Set Detail Page action to green with label “🔍 View Details”.

---

👩‍💼 Outcome

When a user opens the dashboard, they immediately see their 5 most urgent tasks in card format. Each card includes quick-glance info and allows them to:

• ✅ Mark the task complete instantly via flow
• 📝 Edit it on the fly
• 🔍 View or explore more via a detailed page

This scenario brings clarity, ownership, and actionability to team members—without the need to leave the dashboard or switch between tools.