Preview

Note: Query and filtering properties are set via JavaScript properties. See usage below.

Usage

<cs-property-filter filtering-placeholder="Find instances"></cs-property-filter>

<script>
  const filter = document.querySelector('cs-property-filter');
  filter.filteringProperties = [
    { key: 'name', propertyLabel: 'Name', operators: ['=', '!=', ':', '!:'], groupValuesLabel: 'Name values' },
    { key: 'type', propertyLabel: 'Type', operators: ['=', '!='], groupValuesLabel: 'Type values' },
    { key: 'state', propertyLabel: 'State', operators: ['=', '!='], groupValuesLabel: 'State values' },
    { key: 'region', propertyLabel: 'Region', operators: ['=', '!='], groupValuesLabel: 'Region values' },
  ];
  filter.query = {
    tokens: [
      { propertyKey: 'state', operator: '=', value: 'Running' },
      { propertyKey: 'region', operator: '=', value: 'us-east-1' },
    ],
    operation: 'and',
  };
  filter.filteringOptions = [
    { propertyKey: 'state', value: 'Running' },
    { propertyKey: 'state', value: 'Stopped' },
    { propertyKey: 'state', value: 'Terminated' },
    { propertyKey: 'region', value: 'us-east-1' },
    { propertyKey: 'region', value: 'us-west-2' },
    { propertyKey: 'region', value: 'eu-west-1' },
    { propertyKey: 'type', value: 't3.micro' },
    { propertyKey: 'type', value: 't3.small' },
    { propertyKey: 'type', value: 'c5.xlarge' },
  ];
  filter.countText = '5 matches';
</script>

Properties

async-propertiesboolean

Set asyncProperties if you need to load filteringProperties asynchronously. This would cause extra onLoadMore events to fire calling for more properties.

count-textstring

Accepts a human-readable, localized string that indicates the number of results. For example, "1 match" or "165 matches." If the total number of results is unknown, also include an indication that there may be more results than the number listed. For example, "25+ matches."

The count text is only displayed when query.tokens isn't empty. When the countText or query changes, it will be announced to assistive technologies.

custom-groups-textPropertyFilterProps.GroupText[]

An array of objects that contain localized, human-readable strings for the labels of custom groups within the filtering dropdown. Use group property to associate the strings with your custom group of options. Define the following values for each group:

• properties [string]: The group label in the filtering dropdown that contains the list of properties from this group. For example: Tags.
• values [string]: The group label in the filtering dropdown that contains the list of values from this group. For example: Tags values.
• group [string]: The identifier of a custom group.

disabledboolean default: false

If set to true, the filtering input will be disabled. Use it, for example, if you are fetching new items upon filtering change in order to prevent the user from changing the filtering query.

disable-free-text-filteringboolean

Set disableFreeTextFiltering only if you can’t filter the dataset using a filter that is applied to every column, instead of a specific property. This would stop the user from creating such tokens.

enable-token-groupsboolean

Activates token grouping mechanism to support token nesting (up to one level). When true, the query.tokens property is ignored and query.tokenGroups is used instead.

expand-to-viewportboolean

By default, the dropdown height is constrained to fit inside the height of its next scrollable container element. Enabling this property will allow the dropdown to extend beyond that container by using fixed positioning and React Portals.

Set this property if the dropdown would otherwise be constrained by a scrollable container, for example inside table and split view layouts.

We recommend you use discretion, and don't enable this property unless necessary because fixed positioning results in a slight, visible lag when scrolling complex pages.

filtering-aria-labelstring

The label that will be passed down to the Autosuggest ariaLabel property. See the Autosuggest API page for more details.

filtering-error-textstring

Specifies the text to display when a data fetching error occurs. Make sure that you provide recoveryText.

filtering-finished-textstring

Specifies the text to display at the bottom of the dropdown menu after pagination has reached the end.

filtering-loading-textstring

Specifies the text to display when in the loading state.

filtering-optionsReadonlyArray<PropertyFilterProps.FilteringOption> default: []

An array of possible values of the individual filteringProperties. Each element has the following properties:

• propertyKey [string]: The key of the corresponding filtering property in the filteringProperties array.
• value [string]: The value that will be used as a suggestion when creating or modifying a filtering token.
• label [string]: Optional suggestion label to be matched instead of the value.
• tags [string[]]: Optional list of tags giving further guidance about the option.
• filteringTags [string[]]: Optional list of additional tags used for automatic filtering.

Filtering options that require labels can only use = and != operators. The token value must be labelled separately, for example:

const filteringProperty = {
  key: 'state',
  propertyLabel: 'State',
  operators: ['=', '!='].map(operator => ({ operator, format: getStateLabel }))
}
const filteringOptions = [
  { propertyKey: 'state', value: 'STOPPED', label: getStateLabel('STOPPED') },
  { propertyKey: 'state', value: 'STOPPING', label: getStateLabel('STOPPING') },
  { propertyKey: 'state', value: 'RUNNING', label: getStateLabel('RUNNING') },
]

filtering-placeholderstring default: 'Filter by text'

Placeholder for the filtering input.

filtering-propertiesReadonlyArray<PropertyFilterProps.FilteringProperty>required

An array of properties by which the data set can be filtered. Each element has the following properties:

• groupValuesLabel [string]: Localized string to display for the 'Values' group label for a specific property.
• key [string]: The identifier of this property.
• propertyLabel [string]: A human-readable string for the property.
• operators [Array]: A list of all operators supported by this property. If you omit the equals operator because your API does not support it, make sure to set defaultOperator to a supported operator from this list.
• group [string]: Optional identifier of a custom group that this filtering option is assigned to. Use to create additional groups below the default one. Make sure to also define labels for the group in the customGroupsText property. Notice that only one level of options nesting is supported.
• defaultOperator [ComparisonOperator]: Optional parameter that changes the default operator used with this filtering property. Use it only if your API does not support "equals" filtering terms with this property.

filtering-recovery-textstring

Specifies the text for the recovery button. The text is displayed next to the error text. Use the onLoadItems event to perform a recovery action (for example, retrying the request).

filtering-status-typePropertyFilterProps.StatusType

Specifies the current status of loading more options.

• pending - Indicates that no request in progress, but more options may be loaded.
• loading - Indicates that data fetching is in progress.
• finished - Indicates that pagination has finished and no more requests are expected.
• error - Indicates that an error occurred during fetch. You should use recoveryText to enable the user to recover.

free-text-filteringPropertyFilterProps.FreeTextFiltering

An object configuring the operators for free text filtering, which has the following properties:

• operators [Array]: A list of all operators supported for free text filtering. If you omit the contains operator because your API does not support it, make sure to set defaultOperator to a supported operator from this list.
• defaultOperator [ComparisonOperator]: An optional parameter that changes the default operator used for free text filtering. Use this parameter only if your API does not support "contains" free test filtering terms.

hide-operationsboolean

If hideOperations it set, the indicator of the operation (that is, and or or) and the selection of operations (applied to the property and value token) are hidden from the user. Only use when you have a custom filtering logic which combines tokens in different way than the default one. When used, ensure that operations are communicated to the user in another way, or use readOnlyOperations.

This property cannot be set when enableTokenGroups=true.

i18n-stringsPropertyFilterProps.I18nStrings

An object containing all the necessary localized strings required by the component.

loadingboolean

Set to true while the related collection is loading (e.g. during an async filtering action). If set to true, the live announcement of countText by assistive technologies will be paused until it changes back to false.

queryPropertyFilterProps.Queryrequired

An object representing the current query displayed in the property filter, which has three properties: operation, tokens, and tokenGroups. The operation property has two valid values: "and", "or", and controls the join operation to be applied between tokens when filtering the items. The tokens property is an array of objects that will be displayed to the user beneath the filtering input. When enableTokenGroups=true, the tokenGroups property is used instead, which supports nested tokens.

Each token has the following properties:

• value [unknown]: The value of the token to be used as a filter. Can be null or string for default tokens, string[] for enum tokens, and anything for tokens with custom forms.
• propertyKey [string]: The key of the corresponding property in filteringProperties.
• operator ['<' | '<=' | '>' | '>=' | ':' | '!:' | '=' | '!=' | '^' | '!^']: The operator which indicates how to filter the dataset using this token.

read-only-operationsboolean

If readOnlyOperations it set, the indicator of the operation (that is, and or or) is shown, but the operation cannot be changed. This is also supported for nested tokens when enableTokenGroups=true.

token-limitnumber

Specifies the maximum number of displayed tokens. If the property isn't set, all of the tokens are displayed.

token-limit-show-fewer-aria-labelstring

Adds an aria-label to the "Show fewer" button for the token group control. Use to assign unique labels when there are multiple token groups with the same tokenLimitShowFewer label on one page.

token-limit-show-more-aria-labelstring

Adds an aria-label to the "Show more" button for the token group control. Use to assign unique labels when there are multiple token groups with the same tokenLimitShowMore label on one page.

virtual-scrollboolean

If you have more than 500 filteringOptions, enable this flag to apply a performance optimization that makes the filtering experience smoother. We don't recommend enabling the feature if you have less than 500 options, because the improvements to performance are offset by a visible scrolling lag. When you set this flag to true, it removes options that are not currently in view from the DOM.

Slots

customControl

A slot located before the filtering input. Use it if for a Select component if your dataset supports property filter queries only after an initial filter is applied.

customFilterActions

A slot that replaces the standard "Clear filter" button. When using this slot, make sure to still provide a mechanism to clear all filters.

filteringConstraintText

Constraint text that's displayed below the filtering input. Use this to provide additional information about supported filters.

filteringEmpty

Displayed when there are no options to display. This is only shown when statusType is set to finished or not set at all.

Events

changeCustomEvent<PropertyFilterProps.Query>

Fired when the query gets changed. Filter the dataset in response to this event using the values in the detail object.

loadItemsCustomEvent<PropertyFilterProps.LoadItemsDetail>

Use this event to asynchronously load filteringOptions, component currently needs. The detail object contains following properties:

• filteringProperty - The property for which you need to fetch the options.
• filteringOperator - The operator for which you need to fetch the options.
• filteringText - The value that you need to use to fetch options.
• firstPage - Indicates that you should fetch the first page of options for a filteringProperty that match the filteringText.
• samePage - Indicates that you should fetch the same page that you have previously fetched (for example, when the user clicks on the recovery button).