ODataGrid

ODataGrid is an extension to the MUI DataGrid React component which implements features such as sorting, pagination, column selection, and filtering using the OData Standard. This allows you to quickly create a powerful interface for browsing data with minimal back-end code.

Features

Supports DataGrid and DataGridPro
(Almost) drop-in replacement for DataGrid
Fully customisable
Performant & responsive
Supports sorting, pagination, column selection and filtering (dynamic or static filter)
Powerful and intuitive filter/query builder built-in
Supports custom query string parameters for filtering to allow filters which are not natively supported by OData
Integrates with browser history - sorting, page navigation and filtering all create new browser history states which are restored when navigating back/forward.
Responsive column visibility - show or hide columns based on screen size

Demo

Coming soon!

Notes

ODataGrid is still in the fairly early stages of development. I'm not aware of any issues currently, but it hasn't been battle-tested. It also utilises Recoil for state management in the filter builder, which is still considered experimental by Facebook.

Please report any issues that you find, and feel free to make feature requests. This will help to make ODataGrid better.

Installation

ODataGrid can be installed using the appropriate npm package (o-data-grid or o-data-grid-pro).

The following mui packages must also be installed. I recommend using the latest versions where possible, the minimum required version for the data-grid packages is v5.8.0, but any of the other mui packages must be v5.x.x.

These are peer dependencies so won't be installed automatically.

@mui/system
@mui/material
@mui/x-date-pickers
@mui/x-data-grid (minimum v5.8.0) for o-data-grid
@mui/x-data-grid-pro (minimum v5.8.0) for o-data-grid-pro
@mui/icons-material

Usage

Usage is very similar to the regular DataGrid. For the most basic scenario simply change the DataGrid/DataGridPro to the corresponding ODataGrid/ODataGridPro component, add the url property, and remove any unsupported properties.

From there you can start to customise the grid to your needs using the properties available in the API below.

Note: like the DataGrid you should ensure that the columns property keeps the same reference between renders.

If the same reference is not kept, this may trigger duplicate OData requests.

Helpful Tips

Nested properties are supported, to define a column for a nested property flatten it as you would for the query string. E.g. to access Child from { Parent: { Child: "foo" } }, use Parent/Child as the value for field in the column definition. Strong typing is still supported through the result property of the row.

Examples

The demo site isn't ready yet, but you can see some examples of usage here on my GitHub:

Simple example utilising the static $filter filter
More advanced examples utilising the FilterBuilder:
- 1
- 2

API

The ODataGrid API is very similar to the standard DataGrid/DataGridPro APIs, with a few additions and removals.

ODataGridProps/ODataGridProProps

The props are the same as the standard DataGrid props with the following changes:

* = required property

Modifications

Name	Change	Description
`columns*`	Type	See `ODataGridColDef`
`rows`	Removed	Handled internally
`autoPageSize`	Removed	Not supported
`columnVisibilityModel`	Type	Changed to `{ [key: string]: boolean \| Partial<Record<Breakpoint, boolean>> }` to support responsive column visibility Note: providing a value will cause the `hide` property to be ignored on all column definitions.
`disableColumnFilter`	Removed	Not supported - default filtering is replaced
`filterMode`	Removed	Not supported - default filtering is replaced
`filterModel`	Removed	Not supported - default filtering is replaced
`loading`	Removed	Handled internally
`onFilterModelChange`	Removed	Not supported - default filtering is replaced
`onPageChange`	Removed	Handled internally
`onPageSizeChange`	Removed	Handled internally
`page`	Removed	Handled internally
`pageSize`	Removed	Handled internally
`paginationMode`	Removed	Handled internally
`rowCount`	Removed	Handled internally
`sortingMode`	Removed	Handled internally
`sortModel`	Removed	Handled internally

New Properties

Name	Type	Default	Description
`url*`	`string`		URL of the OData endpoint
`alwaysSelect`	`string[]`		Array of entity properties to add to the `$select` clause of the query, even if a column doesn't exist for that property or the column is not visible. If you use the `getRowId` prop of the DataGrid, ensure that property is added here as well.
`defaultPageSize`	`number`	`10`	The default page size to use.
`defaultSortModel`	`GridSortModel`		The default property/properties to sort by.
`disableFilterBuilder`	`boolean`		Disable the filter/query builder if set to `true`
`disableHistory`	`boolean`		Disable the browser history integration for sorting and pagination if set to `true`. Note: this does not disable history integration for the filter builder.
`$filter`	`string`		Static value to use for the `$filter` clause of the query. Note: this also has the effect of setting `disableFilterBuilder` to `true`.
`filterBuilderProps`	`FilterBuilderProps`		Props to be passed to the FilterBuilder.
`requestOptions`	`RequestInit`		Options to use in `fetch()` call to OData endpoint.

ODataGridColDef

The column definition is again similar to the standard GridColDef.

Strong typing is supported through the TRow generic type. The original unflattened type can be accessed using the result property of the grid row parameters. Action columns are also supported using the ODataGridColumns<T> type.

The TDate generic type is also available to specify the date provider type for dateTime columns with a date picker filter.

Modifications

Name	Change	Description
`filterOperators`	Type	Type changed to `Operation[]`
`hide`	Type	Type changed to `boolean \| Partial<Record<Breakpoint, boolean>>` to support responsive column hiding. Note: usage not recommended, use `columnVisibilityModel` instead. This property will be deprecated in the future.
`sortComparator`	Removed	Not supported

New Properties

* = not applicable to collection fields

Name	Type	Default	Description
`autocompleteGroup`	`string`		Group the field should be placed under in the field selection dropdown
`caseSensitive`	`boolean`		If set to `true`, all string operations on the field will be case sensitive. Otherwise `tolower()` is called on all string operations.
`collection*`	`boolean`		Indicates this column is a collection, i.e. is an array. Enables the "Any", "All" and "Count" options.
`collectionFields`	`ODataGridColDef`		Column definitions for the subfields of the collection. Any properties marked with * are not supported.
`datePickerProps`	`DatePickerProps`		Props to pass to the `DatePicker` component for columns with type `date`
`dateTimePickerProps`	`DateTimePickerProps`		Props to pass to the `DateTimePicker` component for columns with type `datetime`
`expand`	`Expand \| Expand[]`		Include related entities using the `$expand` clause.
`filterable`	`boolean`		Hides the field and does not allow filtering in the FilterBuilder when set to `false`.
`filterField`	`string`		If the field name is different to the field which should be used for filtering, provide the field for filtering here. See also: `filterType`.
`filterOnly`	`boolean`	`false`	Set to true if the field is for filtering only and cannot be displayed as a column in the datagrid.
`filterOperators`	`Operation[]`	`["eq", "ne", "gt", "lt", "ge", "le", "contains", "null", "notnull"]`	Array of supported filter operations for the field.
`filterType`	`string`		If the type of the field to be filtered is different to that of the displayed field, provide the type here. See also: `filterField`.
`getCustomFilterString`	`(op: Operation, value: any) => string \| FilterCompute \| boolean`		Function to generate a custom filter string for use in the `$filter` clause. Return `false` to skip and not add it to the `$filter` clause. Also supports the use of the `$compute` clause by returning a `FilterCompute`. The computed property/properties can also be added to `$select` by returning a `ComputeSelect`.
`getCustomQueryString`	`(op: Operation, value: any) => ({ [key: string]: string })`		Function to generate a custom set of query string values to add to the OData request.
`label`	`string`	Defaults to the same value as `headerName` or `field`	Text to be displayed in the field selection dropdown.
`nullable`	`boolean`		Adds an "Unknown" option to the value dropdown for columns with type `boolean` if set to `true`.
`select`	`string`		Additional fields to add to the `$select` clause.
`selectProps`	`{ selectProps?: SelectProps, formControlProps?: FormControlProps, label?: string }`		Props to pass to the `Select`, `FormControl` and `Label` components for this column in the filter. See also: `textFieldProps`.
`sortField`	`string`		If the name of the field to sort by is different to that of the displayed field, provide the name for sorting by here.
`textFieldProps`	`TextFieldProps`		Props to pass to the `TextField` component in the filter for this column. See also: `selectProps`.
`renderCustomInput`	`(value: any, setValue: (v: any) => void) => React.ReactNode`		Function to render a custom component for the "Value" input of the filter. The component should read the value from `value` and use `setValue` to change the value of the filter. See also: `renderCustomFilter`.
`renderCustomFilter`	`(value: any, setValue: (v: any) => void) => React.ReactNode`		Function to render a custom component for filter. The component should read the value from `value` and use `setValue` to change the value of the filter. This overrides the "Operation" input as well as the "Value" input. See also: `renderCustomInput`.

FilterBuilderProps

Name	Type	Description
`autocompleteGroups`	`string[]`	Array of groups for field selection dropdown (used for setting group order)
`autocompleteProps`	`AutocompleteProps`	Props to pass to the `Autocomplete` component used for the field and collection field dropdowns
`datePickerProps`	`DatePickerProps`	Props to pass to the `DatePicker` component used for the value input for columns of type `date`
`datePickerProps`	`DatePickerProps`	Props to pass to the `DateTimePicker` component used for the value input for columns of type `datetime`
`disableHistory`	`boolean`	Disables browser history integration if set to `true`
`filter`	`SerialisedGroup`	Allows setting the state of the FilterBuilder using a `SerialisedGroup`. You could use this to implement filter saving and restoring. Changing the value of this property will cause `restoreState` to be called, but with the `state` property undefined.
`localeText`	`FilterBuilderLocaleText`	Localization strings for `FilterBuilder` (see Localization section)
`localizationProviderProps`	`LocalizationProviderProps`	Props to pass to the `LocalizationProvider` component for the `DatePicker` and `DateTimePicker` components
`onSubmit`	`(params: FilterParameters) => (void \| any)`	Function called when FilterBuilder is submitted (e.g. when the search button is clicked). You should use this to trigger the OData request. `params.filter` is the OData filter string, `params.serialised` is a serialised form of the query which can be used to load the query back into the filter builder.
`onRestoreState`	`(params: FilterParameters, state?: any) => void`	Function called when the state of the FilterBuilder is restored (e.g. from history navigation). You should also use this to trigger the OData request alongside the `onSubmit` callback. `state` is the the value of `history.state` that the query was restored from. `state` will be undefined if the call is as a result of the `filter` property changing.
`searchMenuItems`	`({ label: string, onClick: () => void })[]`	Array of entries to add to the dropdown menu next to the Search button of the `FilterBuilder`

Localization

The FilterBuilder component supports localization like the DataGrid through the localeText property. See below for the translation keys and their default values:

{
  and: "And",
  or: "Or",

  addCondition: "Add Condition",
  addGroup: "Add Group",

  field: "Field",
  operation: "Operation",
  value: "Value",
  collectionOperation: "Operation",
  collectionField: "Field",

  search: "Search",
  reset: "Reset",

  opAny: "Has at least one",
  opAll: "All have",
  opCount: "Count",

  opEq: "=",
  opNe: "≠",
  opGt: ">",
  opLt: "<",
  opGe: "≥",
  opLe: "≤",
  opContains: "Contains",
  opNull: "Is Blank",
  opNotNull: "Is Not Blank"
}

Development

ODataGrid is developed using pnpm. It will probably work fine with npm too, but this hasn't been tested.

To build and run the packages, you first need to install the development packages by running pnpm i in the packages directory. Once you have done that you can build or run the relevant package.

Building

Building is simple, just run pnpm build in packages/o-data-grid or packages/o-data-grid-pro.

The build output is in the build directory.

Running Locally

For ease of testing, each package has a basic dev site included. To start it run pnpm start. This is only a front-end server, you will have to modify the app in dev to point to an OData service of your choice, and add the correct column schema.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

ODataGrid

Features

Demo

Notes

Installation

Usage

Helpful Tips

Examples

API

ODataGridProps/ODataGridProProps

Modifications

New Properties

ODataGridColDef

Modifications

New Properties

FilterBuilderProps

Localization

Development

Building

Running Locally

Files

README.md

Latest commit

History

README.md

File metadata and controls

ODataGrid

Features

Demo

Notes

Installation

Usage

Helpful Tips

Examples

API

ODataGridProps/ODataGridProProps

Modifications

New Properties

ODataGridColDef

Modifications

New Properties

FilterBuilderProps

Localization

Development

Building

Running Locally