Product Documentation
Select a Product:
Find Text:
Submit a question:
Not seeing an answer to a question you might have? You can ask it here and we'll try to update the documentation to address it. If you're making a feature request or reporting a problem, please create a support item for it, instead!
Auto-completion Filter
Purpose
This slicer lets you use autocompletion as part of searching for values in text fields. Autocompletion is a technology that lets the user write some letters within an identifier, word, code, phrase or other text, and the visual predicts one or more possible matches, as choices. If the intended match is shown, it can be easily selected to be included as a report filter.
You can filter using multiple terms, use fuzzy matching, copy-and-paste to and from the slicer, see secondary measures in the lookup list, and much more. There are over 100 settings that control behavior and formatting. The slicer lets you filter efficiently, especially when dealing with identifiers, names, codes, and any text strings of modest length.
Version 6.0 adds searching several columns from one box (Also Search, with suggestions grouped by column), term operators for including, excluding and exact or partial matching, a paste report that shows what matched, quick picks and recent searches, match-reason hints in the suggestion list, and a native-slicer look. See the release notes for the full list.
Data Bucket
The data requirements for the Auto-completion Filter include 6 bucket fields, listed here:
| Field | Type | Description |
|---|---|---|
| Value Source | Text | The text that should be made available for searching. Suggested types of values include identifiers, names, locations, product codes, etc. Up to 4 text columns from the same table can be provided; with multiple columns, values are joined using the Value Separator setting and a picked value filters across all of the columns. |
| Also Search (optional) | Text or numeric | Additional columns searched from the same box (for example, searching names and codes together). Suggestions are grouped by column, and picking one filters that column. |
| Secondary value (optional) | Text or numeric | Zero, one or many values that will be shown in the suggestion list, next to the primary value. This can be used to help the user identify a proper match. Formatting rules are covered by various 'Secondary' settings. |
| Sort Order (optional) | Text or numeric | An optional value that can sort the pick list (as a primary sort value, with the value source becoming a secondary sort field). |
| Additional Tool Tips (optional) | Text or numeric | Zero, one or many fields that can be included in tool tip display, when tool tips are present (i.e. on pill values). |
| Filter Default (optional) | Text | An optional scalar value that is used as the initial filter value. The value can contain multiple text strings separated by commas. The value is reapplied when it changes, such as through cross filtering. This supports use cases such as defaulting filters depending on the user, etc. |
Settings
Presets
| Field | Default | Description | ||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Use Case | None | You can optionally select a preset rules configuration which matches a use case. Picking a preset will automatically set other settings. Every preset also enables Follow Report Theme and sets General Style to 'Native Slicer', so the visual blends with the page's built-in slicers. Settings that are affected include:
| ||||||||||||||||||||||||||||||||||
| Styling | None | You can optionally select a preset formatting configuration which matches a use case. Picking a preset will automatically set other settings. Every preset also enables Follow Report Theme and sets General Style to 'Native Slicer', so the visual blends with the page's built-in slicers. Settings that are affected include:
|
Data and Interaction
| Field | Default | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Filtering | ||||||||||||||
| Only Allow Exact | Off | When enabled, fundamental matching uses 'exact' instead of 'contains', as it relates to what is filtered out from the visual. This does not affect how pick-list choices are generated. Note that contains matching does not require use of wildcard characters. Exact matching also disallows adding partial matches from the autocomplete field to the filter area. Refer to the on-line documentation for more details about how this combines with other settings. In version 6.0, with 'Term Operators' interpreting the full operator set, a term's own operator overrides this setting for that term: ^ (starts with), $ (ends with) and ~ (force fuzzy) match as they would under contains matching and can be added from the entry box, while = and - keep exact matching. See 'Term Operators'. (in 1.5) | ||||||||||||
| Filter Mode | Include | Identifies the default behavior of the filter: either include matched items, or exclude matched items. If toggling is enabled, this can be changed by the user. | ||||||||||||
| Load Behavior | Fully Loaded: No Match, No Data | Specifies the visual's behavior around data loading. Options include:
| ||||||||||||
| Must Select | Off | When enabled, the visual filters out everything until a value is entered. (in 4.3) | ||||||||||||
| Matched plus Blanks | Off | When enabled, blank values will be included in matching by default. (Default does not include blanks, meaning only exact matches are used.) In version 6.0, with columns in 'Also Search (optional)', blanks stay with the Value Source: this setting, the blanks button and 'Blank Lookup Text' add the Value Source's blanks only, and blank Also Search values are not searched. | ||||||||||||
| Allow Filter Prefixes | Off | When enabled, filter terms can be prefixed with '+', '&' or '-' to identify 'union', 'intersect' and 'not include' operations, respectively. (Overrides the Filter Term Combining and Filter Mode settings.) Superseded by 'Term Operators': with this on, Automatic keeps its behaviour exactly; with it off, Automatic interprets the full operator set (set Term Operators to Off to prevent that). (in 3.2) | ||||||||||||
| Term Operators | Automatic | Controls how much of the per-term operator syntax is interpreted. Automatic (default) picks for you: reports that already switched on 'Allow Filter Prefixes' keep exactly the older '+ & -' behaviour, and every other report gets the full operator set. So in a report that never used 'Allow Filter Prefixes', a term that starts with + & - = ^ $ or ~ and is not itself one of your values is now read as an operator ('-Contoso' excludes Contoso), and a term wrapped in double quotes loses its quotes. Choose Off to keep the reading from before 6.0. Data-aware interprets a leading operator only when the term is not itself one of your values. A value that really begins with '-', '=', '^' or '~' (a negative number, an Excel export, a file path) is therefore left alone. To force a term to be taken literally, wrap it in double quotes: "=not an operator". A value picked from the suggestion list that is itself wrapped in double quotes ("Classic", quotes included) is added quoted once more, ""Classic"", so it keeps its quotes - whether it is clicked, reached with the arrow keys, filled in by 'Attempt Completion' or put in by 'Enter Adds Single'; typed in full by hand, the quotes are the escape. While data is still loading the visual cannot yet tell whether a term is one of your values, so it parses the operator. Operators: = exact value, ^ starts with, $ ends with, ~ force fuzzy, and the existing + union, & intersect, - exclude. At most one of '+ & -' followed by at most one of '= ^ $ ~', for example '-=Contoso Ltd' to exclude exactly that value. Under 'Only Allow Exact' an operator overrides exact matching for its own term: ^, $ and ~ match exactly as they do under contains matching (and can be added from the entry box), while = stays a whole-value lookup that never widens through 'Single-Word Token Match in Exact'. - excludes by exact value unless a match operator follows it ('-^Contoso' excludes every value starting with Contoso). + and & have no effect there, and 'List Item Matching' does not apply there to any term, as before. A ^, $ or ~ term that matches nothing is not reported as 'not an exact match'. (in 6.0) | ||||||||||||
| Maximum to Filter | 10000 | Lets you control the maximum number of filtered items that the visual will allow. Using 1 implies a single match. Very large numbers can impact overall performance. In version 6.0, with columns in 'Also Search (optional)', the limit applies to each column's filter separately: every column keeps its first values up to this number, so no column's condition is ever dropped. Adding terms stops once the list holds this many terms, as before. | ||||||||||||
Multiple Values | ||||||||||||||
| Support Multiple | On | When enabled, an area is shown which allows entry / display of one or more filter values (comma or line separated). | ||||||||||||
| Include Current as Type | On | When enabled, entry in the autocomplete field effectively appends to the filter list, even prior to committing the value. | ||||||||||||
| Selecting Auto-Adds | On | When enabled and using multiple values, picking an item from the suggestion list immediately appends it to the value list; when disabled, one still can elect to add it using the add button. | ||||||||||||
| Enter Adds Single | On | When enabled, the Enter key will add the entire match value when there's a single match, or there's a full match that's been autocompleted. When disabled, will only add the typed portion of text in the filter area. | ||||||||||||
| Expand on Add | Off | When enabled, adding a term that matches values will add the matched values to the filter list, instead of the filter term. In version 6.0, with 'Term Operators' interpreting the full operator set, a term that carries an operator (for example -Contoso or ^Contoso) is added as typed instead of being expanded, so an exclusion stays an exclusion. Like any other term, one that matches no values is disallowed unless 'Add Invalid Expand' is on (or 'List Not Fuzzy' is off). | ||||||||||||
| Expand Only if Contains | Off | When enabled, 'expand on add' will only add items which actually contain the entered text. This is primarily useful when fuzzy matching is enabled. (in 2.0) | ||||||||||||
| Allow CSV Entry | Off | When enabled, you can enter comma-separated values in the main entry field and 'adding' will split these into filter terms. | ||||||||||||
| Keep List Open | Off | When enabled and multiple values allowed, the pick list can remain 'open' to allow for multiple selections (closes when focus changes); effectively invokes the 'get list' button functionality after a selection is made. Also keeps the list showing when typing narrows it to a single match that Attempt Completion has filled in. In version 6.0 the description also names the case it always covered: with 'Attempt Completion' on and this setting off, the list closes once typing narrows it to a single value that the box has filled in. The two Power Search presets turn this setting on. (in 1.5) | ||||||||||||
| Retain Partial Match on Add | Off | When enabled and multiple values allowed, the entered portion (when not a full match) is not cleared on an Add (either Enter, Add button or picking from list). Does not apply to 'expand on add'. (in 1.5) | ||||||||||||
| Add Invalid Expand | Off | When enabled, adding a term that does not match any values will still add the term to the filter list. Otherwise, it will be disallowed silently. (in 4.1) | ||||||||||||
| Remove Unmatched When Adding | Off | When enabled, a term that matches nothing under the current filters at the moment it is added to the filter list is
dropped straight away, and a message says how many were dropped. Added means typed or picked in the entry box and added,
pasted into the Text list, typed into the Text list and then leaving it, or brought in by a quick-pick or recent-search
chip (see 'Quick Pick Action'). Only the terms being added are checked: a
term already in the list is never removed, even when a later change to other filters leaves it matching nothing - a
customer that is unmatched under one region can match under another, and removing it would lose the selection. Such
terms can only be marked (see 'Unmatched Term Style'). Nothing is dropped while data is still loading, after a cancelled or interrupted load, while a data update is on its way, or when the visual has reached its capacity, because a value that has not arrived yet cannot be told apart from one that does not exist. Excluding terms ('-') are never dropped, and no term is dropped while 'Filter Mode' (or the include/exclude button) is Exclude. When 'Expand on Add' and 'Add Invalid Expand' are both on, a term added from the entry box (or by a quick pick whose line does not start with '=') is kept, as 'Add Invalid Expand' asks. A term is judged exactly the way the filter judges it. Removing a term that matches nothing usually leaves the filter as it was, but not always: under 'Filter Term Combining' Intersect (or with '&') such a term empties the whole filter, so removing it brings the other terms back. Terms typed into the Text list are checked when you leave the list, never while you are still typing. Off by default. (in 6.0) | ||||||||||||
Quick Picks | ||||||||||||||
| Show Quick Picks | Off | Shows a row of chips between the entry field and the filter list. Each chip applies a named set of terms written under
'Quick Picks'; after them come the viewer's own recent searches where the browser allows them (see 'Recent Searches
Shown') and, with 'Show Save Quick
Pick' on, a '+' button that saves the current list as a new quick pick. Off by default: until it is switched on nothing
about the visual changes - no chip row and no use of browser storage. Requires 'Support Multiple' (a single-value slicer
has no list for a set of terms to go into). The chips use the filter list's font ('Filter Text Size', 'Filter Font') and the colors 'Quick Pick Background Color' and 'Quick Pick Text Color' on the Colors card; left unset they follow the report theme when 'Follow Report Theme' is on, and a high-contrast theme always wins. 'List Spacing' applies above the chip row as well as below it. The row wraps onto a second line and then scrolls, and in the Pills style the pills give up its height. Every chip is a button: Tab reaches the chips after the buttons of the entry row, Enter or Space applies one, and keyboard focus stays on the chip afterwards. A recent-search chip is read by a screen reader as 'Recent search:' followed by all of its terms. (in 6.0) | ||||||||||||
| Quick Picks | One quick pick per line, written Name=term1|term2|term3. Terms are separated by '|' rather than commas, because
commas appear in values too often. Each term is written exactly as you would type it, so the per-term operators and
column names work here too: Key accounts=Contoso Ltd|Northwind Traders, Contoso, not the group=Contoso|-The
Contoso Group, Exact==Contoso Ltd, or with 'Also Search' Widgets=Product:Widget. Only the first '='
ends the name, so a term may itself begin with '='; a name that contains '=' can be wrapped in double quotes. Blank
lines, and lines without a name or without any terms, are ignored; two lines with the same name give two chips. To put a '|' inside a term, wrap the whole term in double quotes: Gauges="12|14 AWG"|10 AWG. The quotes are an escape only where the full operator set is read: 'Term Operators' set to Data-aware, or left on Automatic in a report where 'Allow Filter Prefixes' is off. With Off or Legacy - and with Automatic while 'Allow Filter Prefixes' is on, which Automatic reads as Legacy - the quoted term is still kept whole, but its quotes are searched for as characters. With 'List Item Matching' other than Whole Term a term is cut before its quotes are read, so a quoted term may match nothing there. Spaces around '=' and '|' are ignored unless 'Keep Whitespace' is on, in which case the spaces after '=' and around '|' are part of the terms (write a|b without spaces then); the name is always trimmed, and spaces outside a quoted term's quotes are always ignored. Clicking a chip adds its terms one by one, in the order written, exactly as if each were typed into the entry field and added: 'Expand on Add', 'Expand Only if Contains', 'Add Invalid Expand', 'Only Allow Exact', 'Casing' and 'Maximum to Filter' all apply - a term reached once the list is full is left out, and the 'Too many items' message says how many were added - and the filter then resolves the list under every matching setting, exactly as for typed terms. 'Allow CSV Entry' does not split a chip's term at its commas ('|' is the separator here). See 'Quick Pick Action' for Replace and Add. A line that starts with '=' - =Two picks=Northwind Traders|Proseware - is one written by 'Save current as quick pick'. Its terms are the filter list exactly as it was when it was saved, so its chip puts that list back as it is, the way a recent search does, instead of adding the terms one by one ('Expand on Add' would otherwise expand them again and bring back values that had been removed). Delete the leading '=' to have the terms added like typed terms instead. (in 6.0) | |||||||||||||
| Quick Pick Action | Replace | What clicking a chip does. Replace (the default) first clears the filter list and the entry field, then adds the chip's terms. Add adds them to the terms already in the list. Either way the filter is applied once, after the last term, and kept with the report's filter state as any other change to the list. A recent-search chip, and a chip saved with 'Save current as quick pick', follows the same setting but puts back exactly the list that was searched or saved: its terms are not added again one by one, because 'Expand on Add' would then bring back values that had been removed from it. With 'Remove Unmatched When Adding' on, a term the click brings into the list that matches nothing under the current filters is dropped - except that an author's chip (other than one whose line starts with '=', as 'Save current as quick pick' writes), like the entry field, keeps it when 'Expand on Add' and 'Add Invalid Expand' are both on. (in 6.0) | ||||||||||||
| Show Save Quick Pick | Off | Adds a '+' button at the end of the chip row (a 'Save current as quick pick' link when 'Show Links' is on). It opens a small name box inside the visual: type a name and press Enter or Save to save the current filter list as a quick pick; Escape or Cancel closes the box. If a quick pick with exactly that name exists, its terms are replaced; otherwise a new line is added at the end. The line starts with '=' (=Two picks=Northwind Traders|Proseware): its chip puts back exactly the list that was saved, as a recent search does, rather than adding the terms again one by one (see 'Quick Picks'). Every other line of 'Quick Picks' is kept exactly as written, and the terms are saved in the list's order. A term that cannot be written into a definition line - one containing a line break or an unquoted '|' - is left out, and a message names it. In Power BI Desktop the new line is saved with the report. A viewer in the Power BI Service cannot change the report, so there the new chip lasts only for that viewer's session. (in 6.0) | ||||||||||||
| Recent Searches Shown | 5 | How many of the viewer's recent searches are shown as chips after the quick picks, from 0 to 20 (default 5). At 0 recents
are off and the visual makes no use of browser storage. A search is remembered when it is committed with at least one
term: Enter, Add, a pick from the suggestion list, a paste into the text list, leaving the text list after editing it,
removing a pill, or clicking a chip. Two kinds of search are not remembered: one committed while the column is still
loading under a 'Fully Loaded' Load Behavior (it has not been applied yet), and a very large one - more than about
4,000 characters of terms, typically a big paste or an expanded list. Refining a search - adding or removing terms while
keeping the ones it started with - updates its entry instead of adding one per step, and Reset starts a new search. A
search identical to one of the quick picks (the same terms in the same order) is not kept as a recent, so an author's
chip that leaves exactly its own terms in the list (Replace, with nothing expanded, dropped or cut off) does not push
the viewer's own searches out. A recent chip shows its terms cut at 40 characters, with all
of them in the tooltip, and clicking it puts that exact list back ('Quick Pick Action' decides whether it replaces the
list or is added to it). Recents are kept in the viewer's own browser through Power BI's local-storage permission for custom visuals, per table and column the visual filters (reports that filter the same column share them), and are never saved in the report. A recent search that used an 'Also Search' column (a Product:Widget term) is shown only in visuals that search that column too: elsewhere the term would be read as an ordinary value and match nothing. Power BI clears a visual's stored data 29 days after it was last written, so recents not used for that long are gone. The visual asks for that permission as an optional one: nothing about the visual depends on it, and it is used only while 'Show Quick Picks' is on and this setting is above 0. Where local storage is blocked - turned off for custom visuals by a Power BI administrator, not supported where the report is shown, or refused by the browser - no recent chips appear, the author's quick picks work as usual, the visual notes the reason once in its diagnostic log, and the viewer sees no warning or message about it. (in 6.0) | ||||||||||||
Search Behavior | ||||||||||||||
| Attempt Completion | On | When enabled, as you type, a possible best match may be filled in but you can continue to type a different value. In version 6.0 the active suggestion - the one the box has filled in, or the one the arrow keys moved to - is outlined in the suggestion list, and screen readers are told that the box both completes and lists as you type. The keys work as before. | ||||||||||||
| Backspace Can Trigger | Off | When this is enabled and with Attempt Completion enabled, the Backspace key can increase the characters selected (for completion), instead of clearing them; when disabled, the behavior is closer to a traditional text input. | ||||||||||||
| Matches Favor | Prefer Early Matches | With multiple matches, controls which matches are shown first in the autocompletion list. Early refers to matches close to the start of the source value; late refers to matches close to the end of the source value. | ||||||||||||
| Matches Shown | 10 | The number of possible matches shown in the autocomplete pick list. | ||||||||||||
| Auto-detect Minimum Characters | On | When enabled, the minimum number of characters required for search terms is determined based on your source data. When disabled, the minimum characters setting is used instead. In version 6.0, with columns in 'Also Search (optional)', the minimum is worked out over the values of every column searched, so a short value in an Also Search column (a size code such as XL) can still be picked and filtered. | ||||||||||||
| Minimum Characters | 3 | When auto-detect is disabled, this is the minimum number of characters required before matching is attempted. If this number is too small, performance can be negatively impacted. | ||||||||||||
| Maximum Text Length | 150 | The default of 150 maximum characters can be changed using this setting. Strings longer than this are ignored from the filter and messaging indicates when this happens. Keep in mind: larger values here could negatively impact performance, so evaluate with your dataset. Also, you can suppress this messaging by removing the 'text too long' message text under Formatting. (in 1.6) | ||||||||||||
| Always Show List | On | When enabled (the default), will always try to show a match list, even if fewer than the minimum number of characters are entered, for filtering. Keep in mind: filtering can't be applied until the minimum number of characters are supplied, and the 'too short' message will be shown when enabled. | ||||||||||||
Also Search | ||||||||||||||
| Group Headers | On | Place up to four more columns in the Also Search (optional) field well to search them from the same box as the
Value Source - for example Customer as the Value Source with Product and Order ID in Also Search. Suggestions from each
column are listed under a header naming that column, and picking a suggestion filters the column it came from: 'Widget'
picked under Product filters Product and shows as a 'Product: Widget' pill. Filters on different columns combine with
AND, so a Customer pill and a Product pill together show that customer's rows for that product. A term you type and add without picking filters the Value Source, exactly as before - unless it is exactly a suggestion shown under another column's header (for example after 'Attempt Completion' filled it in, or after arrowing onto it), in which case it filters that column; the same holds for 'Include Current as Type' and for single selection (where the box then shows the column too, Product:Widget, once you press Enter or leave it). The column stays with the text until you edit it. To aim a typed term at a column, start it with the column name and a colon: Product:wid (upper or lower case). This works in the entry box and in the text list, one term per line or comma, and the column name is recognised whatever 'Term Operators' says; operators go after it (Product:-Widget, Product:=Widget). The text list shows the full term (Product:Widget). A column name containing a comma or a line break is written with a space instead, and a second column with the same name gets ' (2)'. Renaming a column in the field well keeps its terms on it, also after the report is reopened. This setting shows the column headers. When only the Value Source has matches no header is shown, so the list looks as it always has. Turned off, suggestions are not grouped; a suggestion from an Also Search column shows its column name in muted text after the value instead. Each column is matched against its own values with every matching setting (contains or exact, term operators, fuzzy matching, casing - Auto-detect casing follows the column a term is aimed at -, 'Minimum Characters' counted after the colon - 'Auto-detect Minimum Characters' works it out over every column's values -, 'Filter Term Combining' within the column), and 'Filter Mode' and the include / exclude button apply to every column. If the terms aimed at one column match nothing, the report shows no data under a 'No Match, No Data' Load Behavior, because the columns combine with AND; under 'No Match, All Data' that column is simply not filtered. A column whose terms are all exclusions ('-') filters out what they match when another column has a filter. 'Maximum to Filter' applies to each column's filter. 'Copy as DAX' copies every column's filter joined with &&. Limitations in 6.0: Secondary Values, Sort Order, Additional Tool Tips, Filter Default and blanks ('Matched plus Blanks', the blanks button, 'Blank Lookup Text') stay with the Value Source; 'Add All Loaded' adds Value Source values only; date and time columns placed in Also Search are not searched. Because Also Search columns are loaded together with the Value Source, the visual receives one row per combination of their values: loading takes longer on large tables, a Secondary Value that is a measure is evaluated per combination and then combined by 'Secondary Aggregation' (right for a sum, not for an average or a distinct count), a Sort Order measure and Additional Tool Tips are taken from the first combination loaded, and pill drill-through (and the context menu) carries that first combination. A report saved with Also Search terms and opened by a version before 6.0 reads 'Product:Widget' as a Value Source term. No effect unless Also Search has columns. (in 6.0) | ||||||||||||
| Matches Shown per Column | 5 | The most suggestions listed under any one column when more than one column has matches, so one column cannot push the others out of the list; the rows are shared out column by column. 'Matches Shown' still limits the whole list, and a column that is alone in the list can use all of it. No effect unless Also Search has columns. (in 6.0) | ||||||||||||
| Value Source First | On | Lists the Value Source's suggestions before those of the Also Search columns, which follow in field-well order. Turned off, the column whose best suggestion is the closest match to what you typed is listed first - a value equal to the text, then one that starts with it, then one containing it as a whole word, then one merely containing it, then a sounds-like match, then a close-spelling match - and columns that tie keep their field-well order. No effect unless Also Search has columns. (in 6.0) | ||||||||||||
| Show Column on Pills | On | Shows the column name in muted text on a pill whose term names a column, for example 'Product: Widget', so pills from different columns cannot be confused; hover the column name to see which column the pill filters. The name is muted only as far as it stays readable - at least 4.5:1 against the pill, the WCAG AA level for text - whether the pill takes the report theme's colours or your own (the visual reads the colours the pill is drawn in); a high-contrast theme shows it in the theme's foreground, and where the pill's colours cannot be read as solid colours it takes the pill's own text colour. Turned off, the pill shows only the value (its remove button still names the column for screen readers). The text list always shows the full term (Product:Widget), since that is what you would type. No effect unless Also Search has columns. (in 6.0) | ||||||||||||
Sort Behavior | ||||||||||||||
| List Sort Direction | Ascending | Controls the sort direction, when a sort is applied to the pick list data. (Applied to any explicit sort field, otherwise the primary value.) | ||||||||||||
| Sort Precedence | Match Favors / Explicit Sort / Value | Controls the sort rules in the face of possible 'match favors' rules and explicit sort values (if provided). 'Match Favors' refers to the Match Favor setting, where one can prefer early or late matches. In version 2.0, added the 'Explicit Sort / Match Favors / Distance / Value' option. (in 1.4) | ||||||||||||
| Maximum Values for Sorting | 5000 | The maximum number of values that can be used for sorting purposes, for the pick list, prior to the entry of minimum characters. (Picking too large of a value can negatively impact performance.) | ||||||||||||
Matching Rules | ||||||||||||||
| Filter Term Combining | Union | Normally, filter list items are combined (OR'ed), but this option lets you change that behavior to require all terms to match the source value (intersect). If 'Only Allow Exact' is true, this setting will always be treated as 'Union'. (in 2.6) | ||||||||||||
| Word Splitting | Disabled | Controls if/how search terms can be split into word fragments and compared to source values. Intersect means all words must be present for a match. Union means any word must be present for a match. (in 1.5) | ||||||||||||
| List Item Matching | Whole Term | Controls whether the whole filter list item is used for matching (default), or only a portion of it is. This allows one to paste in text that contains extra information that can be ignored for the purpose of matching. (in 2.6) | ||||||||||||
| List Item Delimiter | When 'List Item Matching' is set to use a custom delimiter, this is the custom delimiter text to use. (in 2.6) | |||||||||||||
| Casing | Auto-detect | Specifies how casing is handled by the visual, such as if values typed by the user are forced upper or lower case. Options include:
| ||||||||||||
| Case Must Match | Off | When disabled, case is not required to match. | ||||||||||||
| Can Change Case | On | When enabled, the your typed text can be changed to match the case of the corresponding matched source value. (in 1.4) | ||||||||||||
| Ignore Non-alphanumeric | On | When enabled, allows you to skip entry of non-alphanumeric values such as dashes, spaces, etc. In version 6.0 the whole-value comparisons ('Only Allow Exact' and the = operator) and the test for a direct match (which decides, with 'Fuzzy Matching' on or 'Expand Only if Contains', whether a value contains what was typed) skip only spaces, punctuation and symbols here: letters of every alphabet, accented, Cyrillic, Greek or Asian alike, still have to match, so a Cyrillic name followed by 55 is not an exact match for another name followed by 55. Contains matching, the suggestion search and 'Minimum Characters' still skip every character outside a-z and 0-9, as before. | ||||||||||||
| Keep Whitespace | Off | When enabled, whitespace in the search term must match whitespace in the source data (regardless of 'Ignore Non-alphanumeric' setting). (in 1.4) | ||||||||||||
| Retain Characters | You can specifically override 'Ignore Non-alphanumeric' (when enabled) to list characters that should NOT be excluded from matching. For example '@' might be considered important for email lookups. No delimiters are required: all characters in the string are retained for matching. (in 2.7) | |||||||||||||
| Diacritic Neutral | Off | When enabled, internally converts diacritic (accented) characters to ASCII characters, for comparison purposes. This makes data entry somewhat more 'forgiving,' primarily in English locales. | ||||||||||||
| Blank Lookup Text | When provided, this value gets added to the list of possible lookup values (if there is at least one blank value), but when it's selected, it will match blank values (only), including empty strings. Be sure this never matches values in source data, since it takes precedence in this setting. Example: N/A (in 2.7) | |||||||||||||
| Value Separator | - | When multiple fields are provided in the Value Source bucket, their values are joined with this separator to form the lookup string. Selecting a combined value filters the underlying rows across all provided columns. Up to 4 fields can be provided in the Value Source well, all from the same table. All matching behavior (autocomplete, exact/contains, fuzzy, batch expansion) operates against the combined string. Selections filter the underlying rows across all provided columns (a Power BI tuple filter). Note: exclude mode is not supported with multiple value fields; a warning is shown and the filter is not applied until include mode is restored. Choose a separator that does not occur inside your data values to keep combined entries unambiguous. (in 5.2) | ||||||||||||
Fuzzy Matching | ||||||||||||||
| Fuzzy Matching | Off | When enabled, similar text matches are allowed, based on fuzzy matching rules. This is most useful when dealing with whole words, versus codes and identifiers. This makes data entry more forgiving in the face of spelling differences, primarily in English locales. | ||||||||||||
| Fuzzy Algorithm | Standard | Controls what algorithm is used for fuzzy matching. Default is the "Standard" algorithm (the only one available pre-2.0). Options include:
| ||||||||||||
| Fuzzy Custom Map | When the fuzzy matching algorithm is set to 'custom mapping', this field lets you specify character translations, one per line. Each translation should be of the form 'from;to' where the text 'from' is treated as if 'to' for the purposes of matching. For example, "ei;ie" would change occurrences of "ei" to "ie" for the purposes of searching/matching. In this example, if someone misspelled "receive" as "recieve", both word forms would transform to the same underlying value, allowing matching to "work". Notice it's not important that the transformed word is spelled incorrectly: the important thing is it is that all possible forms are mapped to the same target form. The mapping is case-insensitive. The mapping is applied to the source data, and to the entered text, so that the entered text is transformed before matching. (in 2.0) | |||||||||||||
| Maximum Lexical Distance | When set, causes possible matches that are 'further' away from the input text than this lexical distance to be excluded. Similar to Levenshtein distance, but penalizes extra characters less. Relevant when using fuzzy matching algorithms such as double-metaphone. (in 2.0) | |||||||||||||
| List Not Fuzzy | On | When enabled (default), items collected in the multi-select list (or completed in single select) do not 'filter out' using fuzzy matching rules (i.e. the 'Only Allow Exact' setting is considered for exact vs. contains matching). If fuzzy matching is enabled, it only pertains to the lookup list, effectively. When not enabled, each entry can match out based on its own fuzzy matching rules. (in 2.0) | ||||||||||||
| Single-Word Token Match in Exact | Off | When enabled (and Only Allow Exact is on, and Fuzzy Matching is on), a single-word filter list entry expands to every source value where the word appears as a complete token (e.g. typing 'Hollywood' matches every 'Hollywood Blvd'-style value). Expansion is capped by Maximum to Filter. Multi-word filter list entries still require an exact match - typing '6 Hollywood Blvd' will NOT match 'Old 6 Hollywood Blvd Apt 1'. Only affects how filter list items resolve to source values; the autocomplete pick list remains liberally fuzzy regardless. In version 6.0 the complete-token test honors 'Case Must Match', 'Diacritic Neutral' and 'Ignore Non-alphanumeric' (with 'Retain Characters'): with 'Diacritic Neutral' on, 'Jose' is a complete token of 'José Garcia'. An accented or non-Latin letter is no longer taken for a word break, so 'rich' is not a complete token of 'Zürich'. (in 5.1) | ||||||||||||
Advanced | ||||||||||||||
| Persist Values | On | When enabled, filter values that are set in edit mode are preserved when the report is saved, otherwise the visual always starts with no filter. | ||||||||||||
| Maximum Cache (seconds) | 0 | The maximum number of seconds that the visual can continue to hold cached value data, before any external refresh or filter change will trigger a reload. Longer values improve performance at the expense of data currency. A nonzero value can 'see through' filters that may be applied externally by the report, and the reset button can be used to release cached values manually. | ||||||||||||
| Secondary Aggregation | Sum/Concatenate | When using secondary values, controls how to handle cases where multiple secondary values apply to a single primary value. | ||||||||||||
| Use Default Context Menus | Off | When enabled, context menus on text controls will be the browser default as opposed to the Power BI context menu. This gives you the option to use browser menu features (eg. copy, paste). (in 1.5) | ||||||||||||
| Allow Tooltips | On | When enabled, tool-tips may be shown when hovering on pills that have secondary values to show. | ||||||||||||
| Allow Pill Drill-through | Off | When enabled, pills which correspond to 'exact matches' in the source data expose a context menu in a way that supports drill-through. Enabling this may have a significantly negative impact on performance - you should only use this when pre-filtering data, and there is a limit to 10000 rows where this may be applied. In version 6.0, with columns in 'Also Search (optional)', the visual receives one row per combination of Value Source and Also Search values, so a Value Source pill's drill-through carries the first combination loaded (its Also Search values too). A pill that filters an Also Search column has no drill-through. | ||||||||||||
Formatting
| Field | Default | Description |
|---|---|---|
Display & Layout | ||
| General Style | Base Default | Offers some different general styles for the visual. In version 5.2, added the 'Native Slicer' option: the entry areas get a thin border with slight rounding and the buttons become flat, matching the look of the built-in Power BI slicers. The border color is inherited from the current report theme (like standard visuals) so it blends with sibling slicers; set an explicit 'Entry Border Color' to override it. To tighten the visual against its frame, reduce the 'Container Padding' setting. (in 1.7) |
| List Placement | Under Entry | Controls where the pick list is positioned. The default is under the entry text field. In-line allows the list to overlap the entry field, following the caret. Far right places it to the right of the entry field. Native hands the list to the browser, which is the only placement that can extend past the visual's frame - at the cost of the visual's own fonts, colors and highlighting (see documentation). In version 5.4, added the 'Native (can overflow the visual)' option: the pick list is drawn by the browser instead of the visual, so it can extend below the visual's frame. The browser controls its size, fonts and colors, so List Font, List Height, Hover / Highlight / Match Background colors and the Close link do not apply. Attempt Completion, Retain Partial Entered and arrow-key cycling are disabled in this mode. Fuzzy and non-literal matches may not appear in the native list; the match count still includes them. (in 2.5) |
| List Formatting | Line-feeds | Controls the formatting of terms in the text area, when using the Text style. |
| List Style | Text | When supporting multiple values for filtering, determines the style of the multiple filter values. ('Text Pop-up' hides the filter list until it's activated.) |
| Show Links | Off | When enabled, links will be used instead of buttons. Links will use the Message: settings for the text to display. (in 2.4) |
| Can Toggle List Style | Off | When enabled, a button is available that lets the user toggle the list style (when supporting multiple values). |
| Can Toggle Show Blanks | Off | When enabled, a button is available that lets the user toggle the inclusion of blank values. |
| Can Toggle Exact Matching | Off | When enabled, a button is available that lets the user toggle between exact or contains matching modes. (in 5.0) |
| Can Toggle Include Exclude | Off | When enabled, a button is available that lets the user toggle whether the visual is including or excluding matched values. |
| Filter Word Wrap | On | When enabled, word-break word wrapping will be used for the filter area. (in 1.6) |
| Resize Filter to Content | Off | When enabled, the visual height dictates a maximum height, where the filter area can be made smaller dynamically, to fit its content. (in 1.6) |
| Show Add Button | On | When disabled, the add button will be hidden (Enter key can still be used). |
| Show Add All Button | Off | When disabled, the add all button will be hidden. |
| Show Expand-Batch-with-Mappings Button | Off | When enabled, a button is shown that takes every value in the filter list and expands each into its matching source values. The filter list is replaced with the union of all expansions, and a mapping table (matched value, originating term) is copied to the clipboard. Useful both for batch-expanding a list of terms and for auditing how each search term mapped to source values. In version 6.0, with 'Term Operators' interpreting the full operator set, a term that carries an operator (for example -Contoso or ^Contoso) is kept in the list as typed instead of being expanded, so an exclusion stays an exclusion; the mapping lists it on both sides. Like any other term, one that matches no values is dropped unless 'Add Invalid Expand' is on (or 'List Not Fuzzy' is off). With 'Paste Report' on (the default), expanding two or more terms shows the paste report, which lists every term that matched nothing, instead of naming only the first one in 'No matches found'; set 'Paste Report' to Off for the previous message. In the pills style the button now expands the pills and applies the result; before 6.0 it read a hidden copy of the list that only the copy button filled, and the expansion never reached the report's filter. (in 5.1) |
| Expand-Batch-with-Mappings Delimiter | \\t | Delimiter placed between the matched value and the originating term in the mapping table copied to the clipboard. Default is a tab character (paste-friendly for Excel). Use \t for tab. (in 5.1) |
| Show Clear Button | On | When disabled, the clear button will be hidden. |
| Show Get List Button | Off | When disabled, the 'force show list' button will be hidden. (in 1.5) |
| Show Copy Clipboard | Off | When disabled, the copy to clipboard button will be hidden. Note: copy functionality varies based on browser used. (in 2.0) |
| Show Cancel Load | Off | When disabled, the cancel load button will always be hidden. (in 4.0) |
| Show Loading Message | On | When enabled, the loading message will be shown below the value entry control. |
| Loading Indicator Style | Text | Choose how the loading indicator appears. 'None' hides it. 'Text' shows the 'Loading...' message below the entry control (default - matches prior behavior). 'Spinner' replaces the text with a centered spinner overlaid on the visual. The Show Loading Message setting must also be enabled for the indicator to appear. (in 5.1) |
| Show Counts | On | When enabled, rows loaded and matched counts are shown. In version 6.0 screen readers hear a changed count politely, without focus moving - but not while data is loading: the count a load ends on is announced once (nothing, when it is the count already heard). The counts shown on screen are unchanged. |
| Show Close List Link | Off | When enabled, the drop-list includes an extra item - a link - for 'close' (of the list). (in 2.0) |
| Show Match Reason | Inexact only | Marks suggestions that matched for a reason you cannot see in the text itself, so a fuzzy result is
explainable rather than surprising. A row reached by sound carries '~', one reached by close spelling
(or, with the Custom Mapping or Lemmatized algorithm, by that algorithm's rules - hover reads 'Fuzzy match')
carries a double-tilde, and one matched on a whole word inside a longer value carries a middle dot; hover
for the wording (a screen reader hears it after the value). Rows that begin with what you typed, or contain
it as part of a word, are never marked - badging those would put a symbol on nearly every row and teach you
to ignore them. 'Inexact only' (the default) marks just the three above. 'All' is the same set - the kinds with no symbol have nothing to add. 'Off' disables the marks entirely. Not available with the Native list placement, where the browser draws the list and the visual cannot add to a row. (in 6.0) |
| Show Copy as DAX | Off | Adds a button that copies the CURRENTLY APPLIED filter as a DAX predicate, ready to paste into a measure, a calculated column or a calculated table - for example 'Sales'[Customer] IN { "Contoso", "Fabrikam" }. What is copied is what the report is actually filtered by, not what is typed in the box, so terms that matched nothing are not included. Exclude filters are wrapped in NOT ( ... ). With several Value Source columns the tuple form is emitted instead. With columns in 'Also Search (optional)' every filtered column's predicate is copied, joined with && - ( 'Sales'[Customer] IN { "Contoso" } ) && ( 'Sales'[Product] IN { "Widget" } ); that form works in FILTER, measures and calculated columns, and in CALCULATE when the columns come from one table (split it into one argument per column otherwise). While the visual is blanking the report - 'Must Select' with nothing entered, or a 'No Match, No Data' Load Behavior with nothing matched - FALSE() is copied; in Exclude mode that same state excludes nothing, and NOT ( FALSE() ) is copied. When nothing is filtered, nothing is copied and the message says so. The confirmation follows 'Copied Message Duration' (zero shows none) and is also read out by screen readers; a copy the browser refuses shows 'Failed to copy to clipboard.' Like the other entry-row buttons it follows 'Button Background Color' and 'General Style', and with 'Show Links' on it is a 'Copy filter as DAX' link. It sits to the left of the entry field, and Tab reaches it there: right before the entry field (after the operator picker). Off by default. (in 6.0) |
| Show Pill Operator Badges | On | Shows a small badge on any filter pill whose term carries an operator - for example '-' on an excluded term or '=' on an exact one. Pills without an operator are unchanged, so an ordinary report shows no badges at all. The badge exists so that a term which is being INTERPRETED always says so: with 'Term Operators' active, '-Contoso' filters differently from the literal value '-Contoso', and the badge is what tells them apart at a glance. Hover a badge for the operator's meaning. (in 6.0) |
| Show Operator Picker | Off | Adds a small button to the left of the entry field that chooses an operator to apply to the NEXT value you
add - exclude, exact, starts with, ends with or fuzzy - without having to type the operator character.
It applies to a value picked from the suggestion list as well as to a typed one, and with 'Allow CSV Entry'
to every comma-separated term of that entry. A picked value is always taken as that value, even one that
begins with an operator character. The button is shown only with 'Support Multiple' on and 'Term Operators'
interpreting the full operator set; while it is hidden, no operator is applied. Off by default, because the
entry row is already dense; the operator characters work whether or not this button is shown. It follows 'Button Background Color' and the rounding and borders of 'General Style' like the other entry-row buttons, and stays a button when 'Show Links' is on (its label is the operator character itself). From the keyboard, Enter or Space moves to the next operator and keeps focus on the button, and the new operator is announced; a click returns to the entry box. Tab reaches the button where it is on screen, right before the entry field (or before the 'Show Copy as DAX' button, when that is shown). With 'Include Current as Type' on (the default) the text being typed already filters the report, and it does so with the chosen operator, exactly as it will once added - choosing another operator re-applies it. Leaving the entry field without adding the text keeps that filter, operator included. (in 6.0) |
| Operator Picker Is Sticky | Off | Keeps the chosen operator selected after a value is added, so several values can be added with the same operator. Off by default, which means the picker resets to no operator after every add that uses it - safer, because a forgotten sticky operator silently changes every value you add afterwards. (in 6.0) |
| Unmatched Term Style | Off | Marks a filter pill whose term matches nothing under the report's CURRENT filters - for example a customer that only
exists in Germany while another slicer is set to USA. Such a term stays in the list but contributes nothing to the
filter, and without the mark nothing says so. The mark is information only: the pill keeps its place and returns to
normal by itself as soon as the other filters change so that it matches again. Nothing is removed because of it (the
one opt-in exception is 'Remove Unmatched When Adding'). Off (the default) draws every pill the same way, as before 6.0. Dashed border draws the pill's border dashed, in the pill's text colour; Dashed border + strike-through also strikes out the text. The text itself is never faded or recoloured: it keeps the colour every other pill has - the report theme's, your own 'Text Color' and 'Pill Background Color', or a high-contrast theme's - so a marked pill is exactly as legible as the rest. With 'Allow Tooltips' on, hovering a marked pill says why; a screen reader always hears it. While any pill is marked, a 'Remove unmatched' button under the list removes them all in one click (not shown when 'Filter Text Read Only' is on). The Text list styles have no pills to mark: see 'Show Unmatched Terms Line'. A term is judged exactly the way the filter judges it: 'Only Allow Exact', 'Fuzzy Matching', 'List Not Fuzzy', 'Case Must Match', 'Diacritic Neutral', 'Ignore Non-alphanumeric', 'Keep Whitespace', 'Retain Characters', 'List Item Matching' and 'Term Operators' all apply. Excluding terms ('-') are never marked - excluding nothing is harmless - and for the same reason no term is marked while 'Filter Mode' (or the include/exclude button) is Exclude. Under 'Filter Term Combining' Intersect each term is judged on its own. While data is still loading, after a cancelled or interrupted load, when the visual has reached its capacity, while a data update is on its way, or when the other filters leave the visual no data at all (Power BI can send an empty update in passing, so an empty view is not taken as proof), the visual cannot know that a term matches nothing, so nothing is marked; terms shorter than the minimum characters are not marked either (the too-short message covers them). When only which terms match changes, the marks change in place: the pills keep their order, their scroll position and keyboard focus. With 'Maximum Cache (seconds)' above 0 the visual deliberately keeps values from outside the current filters, so a term may go unmarked. A real value that begins with an operator character (such as '-5 Discount Co') is read as a value only while it is in the data; under filters that leave it out it reads as the operator, exactly as the filter reads it - quote it to keep it literal. (in 6.0) |
| Show Unmatched Terms Line | Off | For the Text list styles, where there are no pills to mark: shows one line under the list - for example '2 terms match nothing under the current filters' - with a 'Remove unmatched' button (not shown when 'Filter Text Read Only' is on). The line and the button update when values are added, pasted or removed, when you leave the list, and when the data reloads while you are not typing in the list; they do not change while you are typing (a reload meanwhile shows when you leave the list), so they neither flicker nor interrupt a screen reader. A term is judged exactly as 'Unmatched Term Style' describes. The wording is under Message Text Overrides. Off by default; pill styles are controlled by 'Unmatched Term Style' instead. (in 6.0) |
| Filter Text Read Only | Off | When enabled, the filter text area will be read-only. (in 1.5) |
Paste Report | ||
| Paste Report | Summary with Details link | After you paste a list of several terms - into the filter list, or into the entry box with 'Allow CSV Entry' on - or
click 'Expand Batch with Mappings', the visual reports how each term was matched: exact (the term is one of
your values), inexact (it matched values that begin with it, contain it as a whole word or as part of a word,
or by a close-spelling or sounds-like rule - the same reasons 'Show Match Reason' gives in the suggestion list) or
unmatched (the filter got nothing from it). The filter is applied first, exactly as before; the report never
holds it up and never changes what was applied. Summary with Details link (the default) shows one line with the counts and a Details button that opens the full report. Summary and details opens the full report straight away - except after a paste into the filter list in a visual too small to show the details under the list: they would cover the list you are typing in, so the report opens with its summary line and Details opens the rest. Off shows nothing, and 'Expand Batch with Mappings' reports its first unmatched term as it always has. Nothing appears for a single term, for typed text or for picks from the suggestion list. The details list the unmatched terms first, each with the reason, then the inexact ones with the values each matched, and the exact ones only when 'Paste Report Lists Exact Terms' is on. A term that matched but did not take effect - removed by a '-' term, not common to every term under Intersect, or past 'Maximum to Filter' - says so, and the summary counts it as not applied. The buttons are Copy unmatched, Copy inexact mapping (value and term, separated by the 'Expand Batch with Mappings' delimiter, ready to paste into Excel), Remove unmatched from list (not shown when 'Filter Text Read Only' is on) and Close. The report follows the filter, not the suggestion list: with 'List Not Fuzzy' on, a misspelling that the suggestion list shows is still unmatched, because the filter does not apply it (a '~' term, or 'List Not Fuzzy' off, lets the filter accept it). What counts as exact follows 'Case Must Match', 'Diacritic Neutral', 'Ignore Non-alphanumeric', 'Keep Whitespace' and 'Retain Characters', as it does for the filter. While data is still loading, after a cancelled or interrupted load, or when the visual has reached its capacity, it cannot know that a term matches nothing: the summary says '(index partial)', leaves those terms out, and updates by itself once loading completes. With a Live Filtering 'Load Behavior' a report made while loading keeps '(index partial)' after the load when the filter was applied during the load and not applied again at its end (the list did not change): it never describes matches the report was not filtered by. Remove unmatched checks each term again against the data as it is at that moment and never removes a term it cannot vouch for. Nothing about the paste report is saved in the Power BI report file. It never changes the visual's size: in a small visual the details open over the list (above the suggestions; typing in the entry box closes them back to the summary line). (in 6.0) |
| Paste Report Rows per Group | 25 | The most terms listed under each heading of the paste report details; the rest are counted as '... and N more'. Copy unmatched and Copy inexact mapping always copy every term, not only the ones listed. (in 6.0) |
| Paste Report Auto-hide (seconds) | 0 | Hides the paste report automatically this many seconds after it appears. 0 (the default) keeps it until you close it, paste again or reset the visual. The countdown pauses while the pointer is over the report or keyboard focus is inside it, and starts again when you leave it. In the pop-up Text list style the report is under the open pop-up, so the countdown starts when the pop-up closes. (in 6.0) |
| Paste Report Lists Exact Terms | Off | Also lists the exactly matched terms in the paste report details. Off by default: after a large paste the exact list is long and rarely interesting, and its count is always in the summary line (as is the number of terms, exact ones included, that did not take effect). An exact term that also pulled in other values by contains shows '+N'; values a close-spelling or sounds-like rule pulled in with it are listed after it, and are part of Copy inexact mapping either way. (in 6.0) |
Secondary Values | ||
| Secondary Style | Use Delimiter and Parentheses | Controls general format rules for secondary values. For example, multiple secondary values can be concatenated with a delimiter, or a format string can be used, instead. Format string rules are documented in on-line help. (in 3.0) |
| Secondary: Delimiter | If multiple secondary values are present, identifies what delimiter would be used to separate them. (in 3.0) | |
| Secondary: Format String | ({0}) | This allows you to control placement of all secondary values, with any desired additional literal text. Secondary values are substituted into the string where {0} represents the first value, {1} the second value, and so on. (in 3.0) |
| Secondary Formatting (First) | Auto | Controls the formatting of only the first of any secondary values you provide. (Anything past the first will use 'Auto'.) Note: 'Auto' will use semantic model formatting for the value. |
| Secondary: Currency Code | If the secondary value should be shown as a currency, indicates the currency type, in ISO 4217 currency code format (eg. USD). | |
| Secondary Max Decimal | 2 | For secondary values that are numbers, specifies the maximum number of decimal places. |
| Secondary Min Decimal | 0 | For secondary values that are numbers, specifies the minimum number of decimal places. |
| Secondary Labels from Model | Off | When enabled, labels will be appended to all secondary values, with the label text coming from the field name, as shown in the visual's secondary values well. (in 3.0) |
| Secondary Label | Optional text that can prefix all secondary values in the pick-list. | |
Fonts & Sizes | ||
| Entry Text Size | 12 | The size of the entry and filter text. |
| Entry Font | The font family for the entry text. | |
| Filter Text Size | 10.5 | The size of the text in pills and in the filter text area. |
| Filter Font | The font family for the text in pills and in the filter text area. | |
| List Text Size | 10.5 | The size of the text in the suggestion list. |
| List Text Font | The font family for the text in the suggestion list. | |
| Links Text Size | The size of the text used for links, when the 'show as links' setting is enabled. (in 2.4) | |
| Links Text Font | The font family for links, when the 'show as links' setting is enabled. (in 2.4) | |
| Counter Text Size | The size of the counter text. (in 2.1) | |
| Counter Text Font | The font family for the counter text. (in 2.1) | |
| Status Text Size | The size of the status message text font. (in 3.3) | |
| Status Text Font | The font family for the status message text. (in 3.3) | |
Message Text Overrides | ||
| Loading Text | Loading | Text to show for the 'Loading' message. |
| Loaded Text | loaded | Text to show for the 'loaded' count text. |
| Matched Text | matched | Text to show for the 'matched' count text. |
| Filtered Text | filtered | Text to show for the 'filtered' count text. |
| Filtered Out Text | filtered out | Text to show for the 'filtered out' count text. |
| Various Message Text Overrides | You can change the text shown for various messages, such as when the user tries to add a value that is too short, or when the user tries to add a value that is not an exact match. The text can include placeholders for values, such as {0} or {1}. The placeholders will be replaced with the appropriate values at runtime. | |
| Message: Exclude Mode Unsupported | Exclude mode is not supported with multiple value fields. Switch to include mode to apply the filter. | Text to show when exclude mode is used with multiple Value Source fields (not supported by Power BI tuple filters). (in 5.2) |
| Message: Fields Span Tables | All value fields must come from the same table. Remove fields from other tables. | Text to show when Value Source fields come from different tables (multi-field filtering requires a single table). (in 5.2) |
| Message: Unmatched Term | 1 term matches nothing under the current filters. | The line shown under a Text list style when one term in the list matches nothing under the report's current filters ('Show Unmatched Terms Line' on), next to its 'Remove unmatched' button. Like the other messages, the default text is translated when the visual is localized; text you type here is shown as written. (in 6.0) |
| Message: Unmatched Terms (>1) | {0} terms match nothing under the current filters. | The same line when several terms in the list match nothing under the report's current filters; {0} is the number of terms. Like the other messages, the default text is translated when the visual is localized; text you type here is shown as written. (in 6.0) |
| Message: Unmatched Term Removed | 1 term matched nothing and was removed. | The message shown when 'Remove Unmatched When Adding' dropped one term at the moment it was added, because it matched nothing under the report's current filters; {1} is the term. Like the other messages, the default text is translated when the visual is localized; text you type here is shown as written. (in 6.0) |
| Message: Unmatched Terms Removed (>1) | {0} terms matched nothing and were removed. | The same message when several terms were dropped as they were added; {0} is the number of terms and {1} the first of them. Like the other messages, the default text is translated when the visual is localized; text you type here is shown as written. (in 6.0) |
| Message: Also Search Column Too Large | {0} has more values than the visual can hold; some are not searched. | The message shown when a column in 'Also Search (optional)' has more values than the visual can hold, so some of its values are not searched; {0} is the column name. Like the other messages, the default text is translated when the visual is localized; text you type here is shown as written. (in 6.0) |
| Message: Also Search Columns Too Large (>1) | {1} columns have more values than the visual can hold; some are not searched. | The same message when several Also Search columns have more values than the visual can hold; {0} is the first column's name and {1} the number of columns. Like the other messages, the default text is translated when the visual is localized; text you type here is shown as written. (in 6.0) |
| Various Tool Tip Overrides | You can override the text shown for different tool tips, most of which are shown when hovering over buttons. | |
| Message: Expand Batch with Mappings | Expand Batch with Mappings | Text to show for the Expand-Batch-with-Mappings tool tip. (in 5.1) |
Button Image Overrides | ||
| Image: Reset | An optional override for the image to use for the reset button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 2.6) | |
| Image: Add | An optional override for the image to use for the add button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 2.6) | |
| Image: Append All | An optional override for the image to use for the append all button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 2.6) | |
| Image: Expand Batch with Mappings | An optional override for the image to use for the expand-with-mappings button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 5.1) | |
| Image: Bullet Style | An optional override for the image to use for the bullet style button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 2.6) | |
| Image: Text Style | An optional override for the image to use for the text style button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 2.6) | |
| Image: Copy | An optional override for the image to use for the copy button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 2.6) | |
| Image: Delete | An optional override for the image to use for the delete button (red X). The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 2.6) | |
| Image: Down | An optional override for the image to use for the down (arrow) button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 2.6) | |
| Image: Include | An optional override for the image to use for the include button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 2.6) | |
| Image: Exclude | An optional override for the image to use for the exclude button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 2.6) | |
| Image: Hide | An optional override for the image to use for the hide button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 2.6) | |
| Image: Show | An optional override for the image to use for the show button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 2.6) | |
| Image: Contains | An optional override for the image to use for the contains match button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 5.0) | |
| Image: Exact | An optional override for the image to use for the exact match button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 5.0) | |
| Image: Popup | An optional override for the image to use for show popup button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 3.0) | |
| Image: Popup Filtered | An optional override for the image to use for show popup (filtered) button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 3.0) | |
| Image: Cancel Load | An optional override for the image to use for the cancel load button. The image must be in base64 encoded format (prefixed with 'data:image/png;base64' for example). See https://www.base64-image.de (in 4.0) | |
Localization | ||
| Auto Localize | On | When enabled, many text strings / messages in the visual will be converted to the language determined by the browser, or if a value is provided in the 'Localize to Language' setting, that language code will be used explicitly. Only applies to default message strings. One can provide their own (localized) text though a number of settings (e.g. those with names starting with 'Message:'). (in 3.1) |
| Localize to Language | When 'Auto Localize' is enabled, this setting can override the browser language. This should be the first 2 characters of a standard BCP 47 language code. (in 3.1) | |
Entry & List Sizing | ||
| Entry Minimum Width | Allows for an explicit minimum width on the value entry control, in pixels. | |
| Entry Minimum Width (%) | Allows for an explicit minimum width on the value entry control, as a percentage of total width. (in 2.4) | |
| Entry Maximum Width (%) | Allows for an explicit maximum width on the value entry control, as a percentage of total width. Note: when using list placement to the right, 50% will be used for this setting unless set explicitly. (in 2.5) | |
| Entry Text Height | An optional height override for the entry text box. (0 = default height) (in 3.4) | |
| Filter List Max Height | Allows setting a maximum height for the filter list area (in pixels). Resize Filter to Content takes precedence. 0 is no limit. (in 4.3) | |
| List Spacing | Explicit spacing in pixels between the entry field and the filter list below it. When unset, the default spacing is used; 0 makes the two boxes flush. In version 6.0, when 'Show Quick Picks' is on the same spacing is also applied above the quick-pick chip row, so the entry field, the chips and the filter list stay evenly spaced. (in 5.4) | |
| Bottom Spacing | Explicit spacing in pixels between the filter list and the bottom edge of the visual. When unset, the default spacing is used; 0 makes the list flush with the bottom edge. (Bottom Padding, by contrast, adds a reserve strip on top of this.) (in 5.4) | |
| List Height Ratio | 95 | The suggested percentage of maximum space to use for the pick list maximum height. (in 1.4) |
| Copied Message Duration | 4 | The number of seconds to display the 'copied data to clipboard' message. Use zero to show no message. (in 2.4) |
| List Height Minimum | Allows for an explicit minimum height of the autocomplete list, otherwise a default will be used (if unset or 0). | |
| Container Padding | 4 | Padding (in pixels) around the visual's inner container. Also drives the entry row's horizontal padding (half of this value) and the entry control's padding. In version 5.4: when matching the visual's width to the page's built-in slicers, note that the entry field's total side inset stacks THREE layers: the container's own Padding (General > Properties > Padding - applied by Power BI outside the visual, so no visual setting can change it), plus 1.5x this Container Padding value (this padding plus the entry row's half-value padding), plus a fixed 2px entry control margin. The combination validated against built-in dropdown slicers is: container Padding 0 (set manually), Container Padding 5, Frame Title Padding 0 - which is what the 'Text, Native Compact' styling preset applies (except the outer container Padding, which a preset cannot set). |
| Additional Inner Padding | 0 | Allows additional padding to be included between elements within the visual. |
| Bottom Padding | 0 | Allows additional padding that is applied at the bottom of the visual. This provides a way to build overlapping visuals which lets the pick list seemingly show outside of the visual's defined screen real estate. (See pbix sample.) |
| Placeholder Text | Placeholder text to show in the autocompletion field until a user-entered value is provided. | |
| Filter Placeholder Text | Placeholder text to show in the filter list until a user-entered value is provided. (in 2.6) | |
| Close List Text | Close | Text to show for the 'close' link, when 'Show Close List Link' is enabled. (in 2.0) |
Virtual Frame | ||
| Virtual Height | Draws the visual's frame at this height (in pixels) while the visual itself can be sized taller on the canvas. The area below the frame stays transparent and gives the suggestion list room to spill outside the frame. Turn off the built-in Background and Visual border (General > Effects) and set a Background Color (Colors card) for the frame. Note: the transparent area still captures mouse clicks from anything placed underneath. (in 5.4) | |
| Frame Title | Off | When enabled, draws a title INSIDE the frame, replicating the built-in Title. Needed with Virtual Height because the built-in title bar is painted by Power BI on the visual's background - with the background off (required for the transparent reserve), the built-in title has nothing behind it. Turn off the built-in Title (General > Title) and set the text here instead. (in 5.4) |
| Frame Title Text | The text of the frame title. (in 5.4) | |
| Frame Title Font Size | 12 | Font size in pixels of the frame title. (in 5.4) |
| Frame Title Color | The color of the frame title text. Unset follows the report theme's text color. (in 5.4) | |
| Frame Title Bold | Off | When enabled, the frame title is drawn bold. For the semibold weight of built-in titles, set Frame Title Font to 'Segoe UI Semibold' instead. (in 5.4) |
| Frame Title Font | The font family for the frame title. Unset inherits the visual's font. Built-in titles use 'Segoe UI Semibold' by default. (in 5.4) | |
| Frame Title Padding | Padding in pixels around the frame title (all four sides - the bottom side sets the gap to the entry field). Unset uses the default. (in 5.4) | |
| Frame Border Width | 0 | Width in pixels of the border drawn around the visual's frame, replicating the built-in Visual border. 0 disables the border. (in 5.4) |
| Frame Border Color | The color of the frame border. Unset follows the report theme's border color (like standard visuals). (in 5.4) | |
| Frame Corner Radius | 0 | Rounded corner radius in pixels for the visual's frame, replicating the built-in Rounded corners setting. (in 5.4) |
| Frame Shadow | Off | When enabled, draws a drop shadow around the visual's frame, replicating the built-in Shadow effect. (in 5.4) |
| Shadow Color | The color of the frame shadow. Unset uses black. (in 5.4) | |
| Shadow Blur | 10 | Blur radius in pixels of the frame shadow. (in 5.4) |
| Shadow Distance | 4 | Offset distance in pixels of the frame shadow from the frame. (in 5.4) |
| Shadow Angle | 45 | Direction of the frame shadow in degrees: 0 casts right, 90 casts down, 45 casts bottom-right. (in 5.4) |
| Shadow Opacity | 60 | Opacity of the frame shadow as a percentage. (in 5.4) |
Colors
| Field | Default | Description |
|---|---|---|
General & Background | ||
| Follow Report Theme | Off | When on, any color left unset below inherits from the current report theme (like standard visuals), so the visual blends with sibling visuals on the page. Explicit color choices always take precedence. High-contrast accessibility themes are always honored regardless of this setting. Selecting any Use-case or Styling preset turns this on. (in 5.2) |
| Text Color | The color override for general text within the visual. | |
| Status Message Color | The color override for status message text. (in 3.3) | |
| Background Color | The background color for the visual's whitespace areas. Unset implies 'transparent' (starting in 5.0). | |
| Background Opacity | 0 | The opacity (percentage) for the background color. (Zero is fully transparent and is the default, starting in 5.0.) |
Entry & List Areas | ||
| Entry Background Color | The background color override for the text entry control. | |
| Entry Border Color | The border color for the visual's entry areas. (in 4.2) | |
| Placeholder Text Color | The color to use for placeholder text. (in 3.4) | |
| List Background Color | The background color override for the pick list area. | |
| Filter Background Color | The background color override for the filter text area. | |
| Item Highlight Color | The color override for the highlight color for matched text in items in the suggestion list. | |
| Item Hover Color | The color override for items in the suggestion list, when hovering. | |
| Group Header Background Color | Background of the column headers in the suggestion list - the headers shown when columns are in 'Also Search (optional)' and 'Group Headers' is on. Left unset, the headers sit on a band made by moving the list's background a small step toward its text - very light gray on the default white list - so it shows as a band on a colored or dark list too. Whatever the band, the header text is moved toward the list's text color as far as needed to reach 4.5:1 against it (the WCAG AA level for text); if even the list's text color falls short there, that color is used. A high-contrast theme always wins. (in 6.0) | |
Buttons, Links & Pills | ||
| Button Background Color | The background color for buttons within the visual. (in 1.7) | |
| Links Color | The color override for the link text, when the 'show as links' setting is enabled. (in 2.4) | |
| Pill Background Color | The color override for the background color of pills, in the Pill display style. | |
| Pill Operator Badge Color | Color of the operator badge on a filter pill ('Show Pill Operator Badges') - the '-' of an excluded term, the '=' of an exact one. Left unset, it takes the pill's text color - your 'Text Color', or the report theme's text color when 'Follow Report Theme' is on - so it is as readable as the pill's text on pills you colored yourself too; a high-contrast theme always wins. The badge is drawn at full strength, never faded, so a color chosen here should reach 4.5:1 against the pill background (the WCAG AA level for text) to stay readable. A screen reader hears the operator's meaning after the value ('Contoso, Excluded'). (in 6.0) | |
| Quick Pick Background Color | Background color of the chips that 'Show Quick Picks' draws (the quick picks, and the recent searches where they are available). Left unset, the chips take the report theme's pill background when 'Follow Report Theme' is on, and the visual's own light grey otherwise. A high-contrast theme always wins. (in 6.0) | |
| Quick Pick Text Color | Text color of the chips that 'Show Quick Picks' draws (the quick picks, and the recent searches where they are available). Left unset, the chips take the report theme's foreground when 'Follow Report Theme' is on, and the visual's own dark text otherwise; both defaults reach at least 4.5:1 against the chip (the WCAG AA level for text), and a color chosen here should too. A high-contrast theme always wins. (in 6.0) | |
Other Resources / Links:
Learn more about purchasing one or more user licenses from Microsoft AppSource.