---
title: "User Directory Grid Widget"
date: 2025-07-29
modified: 2025-09-19
author: "userelements_wh8sr3"
url: "https://www.userelements.com/docs/ultimate-member-widgets-for-elementor/ultimate-member-widgets/user-directory-grid-widget/"
markdown_url: "https://www.userelements.com/docs/ultimate-member-widgets-for-elementor/ultimate-member-widgets/user-directory-grid-widget.md"
type: docs
excerpt: "This documentation is part of the Ultimate Member Widgets for Elementor plugin. How to Use the User Directory Grid Widget […]"
---
This documentation is part of the **[Ultimate Member Widgets for Elementor](https://www.userelements.com/ultimate-member-elementor/)** plugin.

## How to Use the User Directory Grid Widget

![](https://www.userelements.com/wp-content/uploads/2025/07/Screenshot-2025-07-28-123853-1024x841.png)#### Pre-requisites

- WordPress 6.0+
- Elementor (Free or Pro)
- Ultimate Member
- Ultimate Member Widgets for Elementor

The User Directory Grid Widget is an Elementor widget designed to display Ultimate Member users in a customizable, responsive grid. It supports filters, AJAX search, pagination, custom meta fields, and extensive styling, ideal for member directories, team showcases, and community listings.

### Key Features

- **Responsive Grid Layout**: Displays users in customizable grid columns (1-6)
- **Advanced Filtering**: Filter users by role, meta fields, and custom criteria
- **Live Search**: Real-time search functionality across user data
- **Pagination**: Multiple pagination styles (Numbers, Load More, Infinite Scroll)
- **Custom Meta Fields**: Display any Ultimate Member custom field
- **AJAX Support**: Dynamic content loading without page refresh

#### How to Add the User Directory Grid Widget

1. Open Elementor editor. (Edit the page where you want to display the user directory.)
2. In Elementor’s widget panel, search for **“User Directory Grid.”**
3. Drag the widget into your page layout.
4. Configure the Settings

![](https://www.userelements.com/wp-content/uploads/2025/07/Screenshot-2025-07-29-114204.png)

#### Displaying Users with Advanced Meta Filters

1. Open Elementor editor
2. Search for **“User Directory Grid”**
3. Go to the **Advanced Filters** tab
4. Set Yes to **Enable Advanced Filters**
5. Click on **Add Item** to select which custom field(s) to use as filters (e.g., department, city, skills)

This feature is ideal for creating searchable directories like job boards, community member lists, or service provider directories.

![](https://www.userelements.com/wp-content/uploads/2025/07/Screenshot-2025-07-29-113003.png)

#### Displaying User Meta Fields

1. Open Elementor editor
2. Search for **“User Directory Grid”**
3. Click on the **User Fields** tab
4. Click on **‘Add Item’** to add the user meta fields from the fields dropdown.

You can reorder fields, change labels, and control visibility for a polished directory layout.

![](https://www.userelements.com/wp-content/uploads/2025/07/Screenshot-2025-07-29-113710.png)

### Technical Implementation (For Developers)

#### PHP Classes

- `UM_ELEMENTOR_LIST_MODULE`: Base widget controller
- `UM_User_Meta_Renderer`: Meta field renderer
- `UM_User_Query_Builder`: Query logic with filters

#### Key PHP Methods

- `render()`: Full HTML render logic
- `get_filtered_users_with_pagination()`
- `render_user_grid()`
- `render_user_item()`

#### CSS Classes

- `.um-user-list-container`, `.um-item-user`, `.um-widget-member-holder`
- `.user-layout-spaced`, `.um-custom-field-container`

#### JavaScript

- File: `assets/js/user-list.js`
- Classes: 
    - `UMUserList`: Master controller
    - `StateManager`, `AjaxManager`, `FilterManager`, `PaginationManager`
- Handles live search, filter interaction, AJAX pagination