Ag-Grid Uuniversal Filter

Ag-Grid Universal Filter is a highly funtional quick filter control that supports multiple data sources and intergrates witht ag-grid.

For examples and help ag-grid-quick-filter

To install

yarn add ag-grid-quick-filter

npm i --save ag-grid-quick-filter

How it works

Ag-Grid Universal Filter is intended to be used a quick filter that works with Ag-Grid or another source to filter across a range of fields. The filter supports static lists of values, values returned from a promise and regular expression matches.

Defining choices

The control has a property called choices that accepts an array of ChoiceDefinitions. The ChoiceDefinition interface is generic and can be set to any when declaring an arry. If the generic parameter is provided, it must be of type OptionType, which has the below defintion;

export interface Option {
  text: string;
  value: any;
}
export type OptionType = string | object | Option;

The only mandatory property is key, which has a number of intrenal uses.

There are three ways the choice definition can be configured to load options.

options

The options property is set if you have a static list of values.

lookUp

The lookUp property is for when you have to load values from another source. The property expects a function that returns a promose of OptionType[].

regExMatch and valueGetter

the regExMatch and valueGetter poperties are used when you do not have a static list of values. The regExMatch poperty will determine if the text the user has input is a match. The valueGetter property will parse the text and return a value. Bother are functions.

It is possible to have definitions that are a combination of either static options or lookups, and regular expressions.

other choice definition properties

text and value

The text and value properties are required if any of the choices are objects and are used to extract an items text or value (both can be set to the same field). If the choices are complex but implement the Option interface then neither are required.

choiceDisplayname

The choiceDisplayname is only required if you want to display a different text to the key as a title, when choices are listed.

maximumSelections

The maximumSelections property is used to limit the number of items that can be selected in this definition.

maxAvailableChoices

The maxAvailableChoices property is used to limit the number of choices that are displayed.

search

The search property is used when the item is complex and control whether the items text or value is compared to the search text. Can be search?: 'text' | 'value' | 'both'.

showSelectedValue

the showSelectedValue property determines whether the control dispaly a complex items value or text

agGridColumn

The agGridColumn property is required if you want the control to automatically update Ag-Grid.

filterType

By default values are assumed to be text, if you want them to be treatedly differently then this needs to be set. Can be "text" | "number" | "date".

Using the Ag-Grid Uuniversal Filter control

When you type text the control will assume that you want to look for equality. If you want a different operation then before you type the text enter an operator.

text

• ! not equals
• % contains
• !% not contains
• %{">"} ends width
• %{"<"} starts width

numbers

• = equals
• ! not equals
• {">"} greater than
• {"<"} less than
• {"<"} greater than or equal to
• {">"} less than or equal to

dates

• = equals
• ! not equals
• {">"} greater than
• {"<"} less than

operands

• & and
• | or

Quick start

A simple string list

const choices: ChoiceDefinition<any>[] = [
  {
    key: "guarantorName",
    prefix: "guarantorName",
    name: "Guarantor Name",
    options: [...]
    replaceExisting: true
  }
];

<AgGridUniversalFilter
  title="Quick Filter"
  choices={choices}
/>

Properties

• title select title and key for cache
• choices choices to present to the user and their behaviour (see choice properties)
• selected? selected items
• showWithNoFilter? Show items even if user has not typed
• cacheLookUp? should looked up items be cached
• cacheTimeToLive? how long should items exist in the cache for in seconds
• cacheExpiryCheck? how often should cached item expiry be checked in seconds
• onChange? notify of change
• disabled? control is disabled
• noItemText? text to display if not items are found
• typePromptText? prompt to tell user to type
• caseSensitive? perform case sensitive matching
• toolTipValueLimit? maxium number of items to display
• maxAvailableChoices? maxium choices to display for all catagories
• hideOnSelect close option list when an item is selected
• noClearTextOnSelect? don't clear input text on selection
• selectIfOnlyOption? select an option if it is the only option available
• agGridApi? if supplied allows automatic filtering of ag-grid

Styles

The easist way to style the control is using style varaibles

{
  --universalSelectBackgroundColor: #14061F;
  --universalSelectFontColor: White;
  --universalSelectDisabledBackgroundColor: #353576;
  --universalSelectSelectedBackgroundColor: #9c9ccb;
  --universalSelectBorder: WhiteSmoke solid 2px;
}

Styles variables

• --universalSelectBackgroundColor controls background color, defaults to White
• --universalSelectBackgroundImage if an image is prefered to a color
• --universalSelectHighlihtedBackgroundColor the color used to highlight an option, defaults to lightgray
• --universalSelectHighlihtedBackgroundImage background version of above
• --universalSelectFontColor cotrols font color, defaults to Black
• --universalSelectSelectedBackgroundColor the background color of a selected item, defaults to lightgray
• --universalSelectSelectedBackgroundImage as above
• --universalSelectDisabledFontColor color of font when disabled
• --universalSelectDisabledBackgroundColor background color then disabled, defaults to darkgray
• --universalSelectDisabledBackgroundImage as above
• --universalSelectListWidth width of the options list, defaults to fill available space
• --universalSelectCatagoryTitleFontWeight catagory title font weight, defaults to bold
• --universalSelectPrefixFontSize catagory title font size, defaults to xx-small
• --universalSelectPrefixFontWeight selection prefix font weight, defaults to bold
• --universalSelectDeslectIconColor deselect icon color
• --universalSelectDeslectHighlightIconColor deselect icon color when mouse hovers
• --universalSelectFontWeight font weight for entire control
• --universalSelectFontFamily font family for entire control
• --universalSelectFontSize font size for entire control
• --universalSelectFontStyle font style for entire control
• --universalSelectDropdownIconSize dropdown icon size, defaults to large
• --universalSelectDropdownIconColor dropdown icon color
• --universalSelectClearSelectionIconSize clear selection icon size, defaults to large
• --universalSelectClearSelectionIconColor clear selection icon color
• --universalSelectClearSelectionIconHighlightColor clear selection icon highlight color
• --universalSelectTitleFontSize title size, defaults to small
• --universalSelectDisabledFontColor disabled font color
• --universalSelectBorder control border, defaults to 2px solid Lightgray
• --universalSelectCatagoryTitleFontSize catagory titlte font size, defautls to x-small
• --universalSelectCatagorFontColor catagory font color
• --universalSelectCatagoryTitleBackgroundColor catagory background color
• --universalSelectCatagoryTitleBackgroundImage as above

Choice apperance properties

• choiceStyle To override the style of a listed choice
• choiceHoverStyle To override the hover style of a list choice
• choiceClassName To override the style of a listed choice using a CSS class
• choiceHoverClassName To override the hover style of a list choice using a CSS class

Selection apperance properties

• selectionStyle To override the style of a selection
• selectionDisabledStyle To override the style of a disabled selection
• selectionClassName To override the style of a selection using a CSS class
• selectionDisabledClassName To override the style of a disabled selection using a CSS class
• deselectStyle To override the style of the deselect icon
• deselectClassName To override the style of the deselect icon using a CSS class
• selectionPrefixStyle To override the style of a selection prefix
• selectionPrefixDisabledStyle To override the style of a selection prefix when disabled
• selectionPrefixClassName To override the style of a selection prefix using a CSS class
• selectionPrefixDisabledClassName To override the style of a selection prefix when disabled using a CSS class
• selectionTextStyle To override the style of the selection text
• selectionTextDisabledStyle To override the style of the selection text when disabled
• selectionTextClassName To override the style of the selection text using a CSS class
• selectionTextDisabledClassName To override the style of the selection text when disabled using a CSS class
• deselectIcon To change the deselect Icon - supports react-icons

General apperance properties

• selectStyle To override the style of the select body
• selectDisabledStyle To override the style of the select body when disabled
• className To override the style of the select body using a CSS class
• disabledClassName To override the style of the select body when disabled using a CSS class
• inputStyle To override the style of the input control
• inputDisabledStyle To override the style of the input control when disabled
• inputClassName To override the style of the input control using a CSS class
• inputDisabledClassName To override the style of the input control when disabled using a CSS class
• clearSelectionStyle To override the style of the clear selection icon
• clearSelectionClassName To override the style of the clear selection icon using a CSS class
• titleStyle To override the style of the controls title
• titleDisabledStyle To override the style of the controls title when disabled
• titleClassName To override the style of the controls title using a CSS class
• titleDisabledClassName To override the style of the controls title when disabled using a CSS class
• dropdownIconStyle To override the style of the dropdown icon
• dropIconClassName To override the style of the dropdown icon using a CSS class
• listStyle To override the style of the dropdown list
• choiceListClassName To override the style of the dropdown list using a CSS class
• loadingTextStyle To override the style of the loading optons text
• loadingTextClassName To override the style of the loading optons text using a CSS class
• catagoryStyle To override the style of the catagory title
• catagoryClassName To override the style of he catagory title using a CSS class
• hideDropdownIcon When set hides dropdown icon
• dropdownIcon To change the dropdown icon - supports react-icons
• clearSelectionIcon To change the clear selection icon - supports react-icons
• hideTitle? When sets hides the control's title
• style controls style
• height controls height
• width controls width
• minWidth controls min width
• maxWidth controls max width

Componenets

• choiceComponent?: (props: ChoiceProps & ChoiceStyle) => JSX.Element;
• selectComponent?: (props: SelectionProps & SelectionStyle) => JSX.Element;