---
title: UniSelector
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
The UniSelector is a [user control](https://docs.microsoft.com/en-us/previous-versions/aspnet/y6wb1a0e\(v=vs.100\)) that provides an interface for selecting items. The source of the selectable items is a list of objects of a specified data class, such as users, sites, page types, etc. The control supports several different selection modes and extensive customization options. You can find examples of the UniSelector in the Xperience administration interface.
The UniSelector is optimized to handle very large amounts of objects, so it has greater performance and scalability than standard selection controls, such as the DropDownList.
> **Note:** **Note**: Using the UniSelector control beyond its most basic functions requires some knowledge of coding and Xperience API. When a user selects an item, the control only stores the values of the selected object internally. Any additional functionality, such as database changes, must be implemented in the handlers of the control's events or using the **Click** event of a Button control used for confirmation.
## Getting started
The following is a step-by-step tutorial that shows how to use the UniSelector to select users from the system and perform a basic task with the selected user:
1. Create a new **Web form** named _User\_UniSelector.aspx_ in your administration web project.
2. Register the UniSelector control by adding the following directive to the beginning of the page code:
```html
<%@ Register src="~/CMSAdminControls/UI/UniSelector/UniSelector.ascx" tagname="UniSelector" tagprefix="cms" %>
```
3. Add the following code into the content area of the page (inside the __ element):
```html
```
> **Info:**
>
> - The **ScriptManager** control is required by the UniSelector control. The sample code manually adds the script manager to be functional as a standalone example. The _ScriptManager_ is typically included on the administration master page, so you do not need to add it in real-world scenarios.
> - The **UniSelector** control is configured to allow the selection of user objects from a drop‑down list and to use the content of the _UserName_ column in its value. See the [Properties](#properties) section for more information about the control's properties.
> - The code also contains a **Button** and **Label** control, organized in a basic table layout, are used to demonstrate how to perform a basic task with the value of the UniSelector.The **cms-bootstrap** class is required if you wish to use the default UniSelector styles.
4. Switch to the code behind of the web form (_User\_UniSelector.aspx.cs_) and add the following code:
> **Note:** **Note**: Adjust the name of the class according to the location of your web form.
```csharp
using CMS.Base.Web.UI;
using CMS.Helpers;
public partial class UniSelectorExample_User_UniSelector : System.Web.UI.Page
{
protected void Page_Load(object sender, EventArgs e)
{
// Registers the default CSS and JavaScript files onto the page (used to style the UniSelector)
CssRegistration.RegisterBootstrap(Page);
ScriptHelper.RegisterBootstrapScripts(Page);
}
///
/// Handles the Click event of the submit button.
///
protected void OKButton_Click(object sender, EventArgs e)
{
// Assigns the value of the UniSelector control to be displayed by the Label
lblButton.Visible = true;
lblButton.Text = ValidationHelper.GetString(UserSelector.Value, null);
}
}
```
> **Info:** This code displays the user name of the selected user when the button on the page is clicked. The code also works if you switch the UniSelector to a **SelectionMode** that allows the selection of multiple users – the user names are all displayed separated by semicolons.
>
> This example only serves as a demonstration and the selection has no permanent effect. You can implement any required functionality, such as changes in the database, using the Xperience API.
>
> An alternative way to work with the selected values is to use handlers of the UniSelector's [events](#events).
5. Save the web form and its code behind file.
6. Right-click the web form in the Solution explorer and select **View in Browser**.
The resulting page displays a drop‑down list containing user names and an **OK** button. If you select a user and click the button, the page displays the corresponding user name below.
## Properties
You can set the following properties for the UniSelector control:
| Property name | Description | Sample value |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| AdditionalColumns | Sets the names of the database columns that the UniSelector loads with the objects of the specified data class in addition to the columns required by default. | |
| AdditionalSearchColumns | May be used to expand the search functionality in the object selection dialog. The columns specified through this property are included in the search in addition to the display name column of the given type of object.
Enter the column names separated by commas. | "UserName, Email"; |
| AllowAll | Indicates whether the selector offers the _all_ value. | |
| AllowEditTextBox | Indicates whether users can edit the value of the text box displayed in _SingleTextBox_ or _MultipleTextBox_ **SelectionMode**. | |
| AllowEmpty | Indicates whether the selector allows empty values.
If enabled, the _(none)_ value is available in _SingleDropDownList_ **SelectionMode** and the **Clear** button is displayed in _SingleTextBox_ and _MultipleTextBox_ mode.
When an empty value is used, the default **Value** of the control is:
_0_ in _SingleDropDownList_ **SelectionMode**
An empty string in the remaining modes | |
| AllRecordValue | Contains the value used when the _(all)_ item is selected in _SingleDropDownList_ **SelectionMode**. The default value is -1. | |
| ButtonImage | Sets the path of an image. If specified, the control displays the selection button as a LinkButton using this image. Only applies if the **SelectionMode** is _SingleButton_ or _MultipleButton_. | "\~/App\_Themes/Default/Images/SampleImage.png" |
| DialogWindowHeight | Sets the default height of the selection window. | |
| DialogWindowName | Specifies the name of the selection window to prevent conflicts between multiple UniSelector controls. | |
| DialogWindowWidth | Sets the default width of the selection window. | |
| DisplayNameFormat | Modifies the format of the display names of objects in the selection list.
To correctly display values of objects, use macro expressions in format _{%ColumnName%}_. The control automatically loads the columns required by the macros. | "{%FullName%}, {%Email%}" |
| EditItemPageUrl | Specifies the URL of a custom page that handles the editing of the selected object. If a value is entered, the control displays an edit button that links to the specified URL. Only available for _SingleTextBox_ and _SingleDropDownList_ **SelectionMode**.
The URL may contain macros in format _##ID##_, which are resolved into the value of the selected object's ID column. For example, _?userid=##USERID##_ contains the ID of the currently selected user for a UniSelector set to use the _cms.user_ **ObjectType**. | |
| EditWindowName | Specifies the name of the object editing window to prevent conflicts between multiple UniSelector controls. | |
| EmptyReplacement | Sets a string that the control displays in the selection list as a replacement value for objects whose display name column is empty. | "N/A" |
| Enabled | Indicates whether the control is enabled. | |
| EnabledColumnName | Specifies the name of the column that determines if the selected object is enabled. | |
| FilterControl | Path to the filter control (.ascx file; must inherit from the _CMSAbstractBaseFilterControl_ class) that the UniSelector uses for custom filtering in the selection window. | "\~/CMSFormControls/Filters/CustomFilter.ascx" |
| GridName | Path to the XML configuration file of the [UniGrid](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid.md) control used to display and select objects in _Multiple_ **SelectionMode**.**Note:** When using UniGrid together with UniSelector, do not specify the [objecttypeelement](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid/reference-unigrid-definition.md) in the UnigGrid's configuration file. Configuring an additional data source in the UniGrid configuration file may cause undesirable behavior and lead to errors. | |
| IconPath | Sets the path to the image used in the title of the selection window. | |
| ItemsPerPage | Sets the maximum amount of displayed selected items per page in _Multiple_ **SelectionMode**. | |
| LocalizeItems | Indicates whether the control resolves [localization expressions](https://docs.kentico.com/13/multilingual-websites/setting-up-a-multilingual-user-interface/localizing-text-fields.md) (macros). | |
| MaxDisplayedItems | Sets the maximum amount of items displayed in the list when the **SelectionMode** is _SingleDropDownList_, if the number of selectable objects is higher than the value of the **MaxDisplayedTotalItems** property. Users can select the remaining objects in a dialog that can be opened through the _(more items...)_ option.
The default value is 25.
You can set a default value globally for all UniSelectors in your project through the **CMSSelectorMaxDisplayedItems** key in the __ section of your **web.config**. | |
| MaxDisplayedTotalItems | If the total number of selectable objects is lower than the value of this property, all of them are available in the list in _SingleDropDownList_ **SelectionMode**. If there are more items, the length of the list matches the value of the **MaxDisplayedItems** property and the _(more items...)_ option is included.
The default value is 50.
You can set a default value globally for all UniSelectors in your project through the **CMSSelectorMaxDisplayedTotalItems** key in the __ section of your **web.config**. | |
| NewItemPageUrl | Specifies the URL of a custom page that handles the creation of new objects. If a value is entered, the control displays a new button that links to the specified URL. Only available for _SingleTextBox_ **SelectionMode**. | |
| NoneRecordValue | Contains the value used when the _(none)_ item is selected in _SingleDropDownList_ **SelectionMode**. The default value is 0. | |
| ObjectType | Specifies the type of the objects available for selection.
Enter the appropriate object type value. To find the value for specific object types, open the **System** application in the Xperience administration interface and select the **Object types** tab. | "cms.user" |
| OrderBy | Contains the ORDER BY clause that determines the order of objects. Also affects the order in the selection window. | |
| RemoveConfirmation | Specifies the text of the confirmation message displayed when removing selected items from the UniSelector. Entering an empty string disables the confirmation message. | |
| ResourcePrefix | Determines the prefix added to the full names of [resource strings](https://docs.kentico.com/13/multilingual-websites/setting-up-a-multilingual-user-interface/working-with-resource-strings.md) containing the labels of the various interface elements displayed by the UniSelector. Allows you to assign custom strings to the control.
You can create custom strings in the Xperience administration using the **Localization** application. The keys of these strings must use the following format:
_.general._
The UniSelector uses the following string names:
**additems** - text caption of the add items button used to open the selection window in _Multiple_ mode
**all** - name of the list item representing the selection of all available objects in _SingleDropDownList_ mode
**clear** - text caption of the clear button used in TextBox modes
**edit** - text caption of the edit button used in _SingleTextBox_ and _SingleDropDownList_ mode
**empty** - name of the list item representing an empty selection in _SingleDropDownList_ mode
**itemname** - header text of the column containing the names of objects in the selection window and the UniGrid displaying selected objects in _Multiple_ mode
**moreitems** - name of the list item that opens the selection window if the maximum amount of list items is exceeded in _SingleDropDownList_ mode
**new** - text caption of the new button used in _SingleTextBox_ mode
**newitem** - name of the list item that opens the new item page in _SingleDropDownList_ mode
**nodata** - text message displayed in _Multiple_ mode if no objects are selected and the **ZeroRowsText** property is not defined
**pleaseselectitem** - text of the JavaScript alert displayed when the edit button is used when no object is selected
**removeall** - text caption of the button used to deselect all objects in _Multiple_ mode
**removeselected** - text caption of the button used to deselect the specified objects in _Multiple_ mode
**confirmremove** - if set, a confirmation dialog appears when removing selected objects in _Multiple_ mode, with the string text as the confirmation message
**confirmremoveall** - if set, a confirmation dialog appears when removing all objects in _Multiple_ mode, with the string text as the confirmation message
**select** - text caption of the select button used to open the selection window in TextBox and Button modes
**selectitem** - text of the labels associated with the action elements used by the UniSelector; also sets the title of the selection window (Note: The keys for custom _selectitem_ strings do not contain the _general_ prefix, i.e. use only _.selectitem_) | "mycustom" |
| ReturnColumnName | Specifies the name of the column used for the values of selected objects by the UniSelector. If empty, the ID column is used.
To ensure correct functionality of the control, the column must be a unique identifier for the given object type. | |
| SelectionMode | Determines the type of the selection dialog displayed by the control. The value of this property affects the behavior of many of the other properties of the UniSelector control.
The following modes are available:
**SingleTextBox** - consists of a button that allows the selection of one object and a TextBox displaying the selected value.
**MultipleTextBox** - consists of a button that allows the selection of multiple objects and a TextBox displaying the selected values.
**SingleDropDownList** - displays a drop‑down list containing objects. If necessary, the selection window can be opened by selecting _(more items ...)_ from the list.
**Multiple** - consists of a [UniGrid](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid.md) control displaying the selected objects and buttons that can be used to add or remove them.
**SingleButton** - consists of a button that allows the selection of one object.
**MultipleButton** - consists of a button that allows the selection of multiple objects. | "SingleTextBox"
"MultipleTextBox"
"SingleDropDownList"
"Multiple"
"SingleButton"
"MultipleButton" |
| SpecialFields | Gets or sets a two dimensional string array that contains custom items displayed in _SingleDropDownList_ **SelectionMode**. The first value in the array is the name of the item in the list, the second represents the value of that item when it is selected. | |
| UseDefaultNameFilter | Indicates whether the selection window uses the default name filter. Allows you to disable the default filter if a custom filter is specified through the **FilterControl** property. | |
| Value | Gets or sets the value of the object selected in the UniSelector. The control loads the value from the column specified in the **ReturnColumnName** property. | |
| ValuesSeparator | Specifies the character used to separate selected values in the case of multiple selection. Must be a single character.
The default separator is a semicolon (" ; "). | |
| WhereCondition | Contains the WHERE clause of the SQL query that loads the list of objects available for selection. | |
| ZeroRowsText | Specifies the text displayed when no objects are selected in _Multiple_ **SelectionMode**. | |
## Events
You can handle the following events in the UniSelector's life cycle:
| Event name | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OnItemsSelected | Occurs when users select objects in _SingleButton_ and _MultipleButton_ **Selection Mode**. This event is **not** raised in other modes. |
| OnSelectionChanged | Occurs when the set of selected objects is changed. The event is not raised in _SingleButton_ or _MultipleButton_ **SelectionMode** and may not always be triggered in TextBox modes depending on how the selection is changed.
You can use this event to perform tasks with selected objects in _Multiple_ mode without using a confirmation button. |