# protonus

> React UI library for building CRUD/reference interfaces over OData (and custom data providers).

Latest version **1.0.10** (published 2026-11-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install protonus
pnpm add protonus
yarn add protonus
bun add protonus
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.10 |
| Published | 2026-11-19 |
| First published | 2023-11-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.12.0 |
| Dependencies | 4 |
| Unpacked size | 866.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | custis-oss |
| Keywords | react, antd, table, odata, crud, metadata |

## Links

- npm: https://www.npmjs.com/package/protonus
- Repository: https://git.custis.ru/pub/github/protonus
- npm.io page: https://npm.io/package/protonus

## Dependencies (4)

- [deepmerge](https://npm.io/package/deepmerge.md) 4.3.1
- [clone-deep](https://npm.io/package/clone-deep.md) 4.0.1
- [fast-deep-equal](https://npm.io/package/fast-deep-equal.md) 3.1.3
- [lodash.debounce](https://npm.io/package/lodash.debounce.md) 4.0.8

## Alternatives

- [@lexical/table](https://npm.io/package/@lexical/table.md) — 3.0M weekly downloads
- [mantine-datatable](https://npm.io/package/mantine-datatable.md) — 98.2K weekly downloads
- [react-native-collapsible-tab-view](https://npm.io/package/react-native-collapsible-tab-view.md) — 70.6K weekly downloads
- [@handsontable/vue3](https://npm.io/package/@handsontable/vue3.md) — 16.1K weekly downloads
- [vuewordcloud](https://npm.io/package/vuewordcloud.md) — 7.2K weekly downloads

## Recent versions

- 1.0.10 (latest) — 2026-11-19
- 0.1.13 — 2023-11-24
- 0.1.12 — 2023-11-24
- 0.1.7 — 2023-11-22
- 0.1.1 — 2023-11-21
- 0.1.0 — 2023-11-21

## README

# protonus

React UI library for building CRUD/reference interfaces over OData (and custom data providers).

- Metadata-driven tables, cards, editors, fields, filters and sorters
- OData V4 provider with `$select` / `$expand` / `$filter` / `$orderby` support
- TypeScript source and generated `.d.ts` declarations
- React 18/19, Ant Design 5/6, React Router 6/7

## Install

```bash
npm i protonus antd @ant-design/icons antd-table-ext dayjs react react-dom react-router-dom
```

The major versions of `antd` and `@ant-design/icons` must match:

| Stack | antd | @ant-design/icons | React | react-router-dom |
|---|---|---|---|---|
| Latest | `^6.7.0` | `^6.3.0` | `^19.0.0` | `^7.0.0` |
| Legacy | `^5.29.0` | `^5.6.0` | `^18.2.0` | `^6.28.0` |

## Quick start

```tsx
import { useMetadata, useList, Table } from 'protonus';

const userMetadata = {
    entity: 'Users',
    key: 'id',
    properties: [
        { dataIndex: 'id', type: 'number' },
        { dataIndex: 'name', type: 'string', required: true },
        { dataIndex: 'createdAt', type: 'datetime' }
    ]
};

export function UsersPage() {
    const metadata = useMetadata(userMetadata);
    const list = useList({ metadata });

    return <Table metadata={metadata} list={list} />;
}
```

The default data provider reads `globalSettings.dataProvider.odataPath`. Set it once during application bootstrap:

```ts
import protonus from 'protonus';

protonus.dataProvider.odataPath = 'https://example.com/odata';
```

## Settings

`globalSettings` remains the backward-compatible default. `createSettings` and `SettingsProvider` scope the data provider, `pageSize`, hierarchical loading, metadata types/defaults and the state hooks:

```tsx
import { createSettings, SettingsProvider } from 'protonus';

const settings = createSettings({
    pageSize: 50,
    dataProvider: myProvider
});

<SettingsProvider settings={settings}>
    <App />
</SettingsProvider>
```

`useList`, `useEntity`, `useMetadata` and the metadata layer read settings from the provider and fall back to `globalSettings`.

UI display settings (`locale`, date formats, `onApply`, `editInCard`, field/appearance defaults) are still read from `globalSettings`. Configure them globally if you need a different locale or editing behavior.

### URL state limitation

Row selection is stored in the URL as a comma-separated list (`rowChSel`). String keys containing a literal comma are not supported by this storage format.

## Metadata and types

Property types: `string`, `text`, `number`, `boolean`, `enum`, `date`, `datetime`, `duration`, `entity`, `file`, `dictionary`, `color`, `code`, `expression`, `chain`, `function`.

Data-provider hooks can be configured per property:

```ts
{
    dataIndex: 'customer/name',
    type: 'string',
    filterSerialize: (value) => JSON.stringify(value),
    filterDeserialize: (value) => JSON.parse(value)
}
```

## Custom data providers

Pass a provider to `useList` / `useEntity`, or register it in settings:

```ts
const list = useList({ metadata, dataProvider: myProvider });
const entity = useEntity({ metadata, id, dataProvider: myProvider });
```

A provider implements the methods used by the hooks: `getList`, `getEntity`, `changeData`, `deleteData`, and optionally `getParents`.

## AGG Grid

The AGG Grid integration is an optional example, not part of the published package. See `src/examples/aggrid`.

## SSR and styles

`protonus` is a client-side library. Hooks and components use `window`, `document`, `localStorage` and browser history, so server-side rendering is not officially supported. If SSR is required, render the library only on the client after hydration.

Styles are imported by components and injected at runtime via `vite-plugin-css-injected-by-js`; the package does not ship a standalone CSS file. Importing `protonus` on the client is enough to load its styles.
## Development

```bash
npm test            # unit/integration tests
npm run typecheck   # TypeScript
npm run lint        # ESLint
npm run build       # ESM build + declarations
```

## License

MIT

---
_Source: https://npm.io/package/protonus · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
