{"id":27184220,"url":"https://github.com/queritylib/querity-react","last_synced_at":"2026-02-03T13:14:20.998Z","repository":{"id":286783788,"uuid":"962127018","full_name":"queritylib/querity-react","owner":"queritylib","description":"Querity React Components","archived":false,"fork":false,"pushed_at":"2026-02-01T08:25:54.000Z","size":1613,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-01T19:04:41.596Z","etag":null,"topics":["database","querity","query-builder","react","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@queritylib/react","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/queritylib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-07T17:32:25.000Z","updated_at":"2026-02-01T08:25:52.000Z","dependencies_parsed_at":"2025-08-28T16:25:28.196Z","dependency_job_id":"9c2488a0-a8ee-45e2-9c3e-cfef2d2124d6","html_url":"https://github.com/queritylib/querity-react","commit_stats":null,"previous_names":["queritylib/querity-react"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/queritylib/querity-react","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queritylib%2Fquerity-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queritylib%2Fquerity-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queritylib%2Fquerity-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queritylib%2Fquerity-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/queritylib","download_url":"https://codeload.github.com/queritylib/querity-react/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/queritylib%2Fquerity-react/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29046503,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T10:09:22.136Z","status":"ssl_error","status_checked_at":"2026-02-03T10:09:16.814Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","querity","query-builder","react","typescript"],"created_at":"2025-04-09T16:38:22.606Z","updated_at":"2026-02-03T13:14:20.972Z","avatar_url":"https://github.com/queritylib.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Querity React Components\n========================\n\n## Introduction\n\n**Querity React Components** is a set of React components designed to simplify the creation of user interfaces for querying data from Java backends using the [Querity library](https://github.com/queritylib/querity).\n\n[Querity](https://github.com/queritylib/querity) is a Java query builder that enables developers to construct complex queries using a simple query language or a fluent Java API. It supports various data sources, including both SQL and NoSQL databases.\n\nThis component library is built with **TypeScript** and aims to keep peer dependencies to a minimum, ensuring a lightweight and flexible integration.\n\n## Demo\n\nCheck out the simplest demo application using Querity at [querity-demo](https://github.com/queritylib/querity-demo).\n\n## Requirements\n\n- React 18 or 19 (peer dependency)\n\n## Installation\n\nYou can install the package using **npm** or **yarn**:\n\n```sh\nnpm install @queritylib/react\n```\n\nor\n\n```sh\nyarn add @queritylib/react\n```\n\n## Provider \u0026 Styling\n\nTo use the Querity components, you need to wrap your application with the `QuerityComponentsProvider`. This provider is responsible for providing the HTML components and the CSS styles needed for the Querity components to function properly.\n\nYou can override the default components and styles by passing custom components and styles to the provider.\n\nThis allows you to use any CSS framework or custom styles you prefer, such as **Tailwind CSS**, **MUI**, **Bootstrap**, or any other CSS-in-JS solution.\n\n### Usage\n\n#### With default theme\n\nWrap your application with the `QuerityComponentsProvider` and use the default components:\n\n```tsx\nimport { \n  QuerityComponentsProvider, \n  defaultQuerityComponents, \n  QuerityField, \n  QuerityBuilderUI \n} from \"@queritylib/react\";\n\nfunction App() {\n  return (\n    \u003cQuerityComponentsProvider value={...defaultQuerityComponents}\u003e\n      \u003cQuerityField /\u003e\n      \u003cQuerityBuilderUI /\u003e\n    \u003c/QuerityComponentsProvider\u003e\n  );\n}\n```\n\nAnd import the default theme CSS file:\n\n```css\n@import '@queritylib/react/themes/default/style.css';\n```\n\n#### Custom components styled with **Tailwind CSS**\n\nDon't import the default theme CSS file, but instead use your own CSS framework or custom styles.\n\n```tsx\nimport {\n  QuerityComponentsProvider,\n  defaultQuerityComponents,\n  QuerityField,\n  QuerityBuilderUI\n} from \"@queritylib/react\";\n\nconst querityComponents: ComponentOverrides = {\n  ...defaultQuerityComponents,\n  Input: (props) =\u003e \u003cinput {...props} className={`${props.className} border p-2`} /\u003e,\n  Select: (props) =\u003e \u003cselect {...props} className={`${props.className} border p-2`} /\u003e,\n  Button: (props) =\u003e \u003cbutton {...props} className={`${props.className} bg-gray-200 p-2 cursor-pointer`} /\u003e,\n  Checkbox: (props) =\u003e (\n    \u003clabel className=\"inline-flex items-center cursor-pointer\"\u003e\n      \u003cinput type=\"checkbox\" {...props} className=\"sr-only peer\" /\u003e\n      \u003cdiv\n        className=\"relative w-11 h-6 bg-gray-200 peer-focus:outline-none peer-focus:ring-4 peer-focus:ring-blue-300 dark:peer-focus:ring-blue-800 rounded-full peer dark:bg-gray-700 peer-checked:after:translate-x-full rtl:peer-checked:after:-translate-x-full peer-checked:after:border-white after:content-[''] after:absolute after:top-[2px] after:start-[2px] after:bg-white after:border-gray-300 after:border after:rounded-full after:h-5 after:w-5 after:transition-all dark:border-gray-600 peer-checked:bg-blue-600 dark:peer-checked:bg-blue-600\"\u003e\u003c/div\u003e\n      \u003cspan className=\"ms-3 text-sm font-medium text-gray-900 dark:text-gray-300\"\u003e{props.label}\u003c/span\u003e\n    \u003c/label\u003e\n  )\n};\n\nfunction App() {\n  return (\n    \u003cQuerityComponentsProvider value={querityComponents}\u003e\n      \u003cQuerityField /\u003e\n      \u003cQuerityBuilderUI /\u003e\n    \u003c/QuerityComponentsProvider\u003e\n  );\n}\n```\n\nSee `src/themes/default/style.css` as an example of how to style the default components.\n\n## Components\n\n### QuerityField\n\n`QuerityField` is a text input component designed for entering and validating queries. It includes built-in validation, event handling, and customizable styling.\n\nThe invalid state can be styled by detecting the `aria-invalid` attribute.\n\nHere's how it looks (with custom styles, see [Provider \u0026 Styling](#provider--styling)):\n\n![QuerityField with valid query](/assets/querity-field-valid.png)\n\n![QuerityField with invalid query](/assets/querity-field-invalid.png)\n\n#### Usage\n\n```tsx\nimport { QuerityField } from \"@queritylib/react\";\n\n\u003cQuerityField\n  value=\"\" // Optional: Default query value\n  placeholder=\"Enter query\" // Optional: Placeholder text\n  className=\"custom-class\" // Optional: Custom CSS class\n  onChange={(value) =\u003e console.log(value)} // Optional: Handle query input change\n  onEnter={(value) =\u003e console.log(value)} // Optional: Handle Enter key press\n  onInvalidQuery={(error) =\u003e console.log(error)} // Optional: Handle invalid queries\n/\u003e\n```\n\nTo apply a style when state is invalid add this CSS to your stylesheet:\n\n```css\n.querity-field[aria-invalid=\"true\"] {\n  border-color: red;\n}\n```\n\n#### Props\n\n| Prop             | Type                      | Description                             | Default |\n|------------------|---------------------------|-----------------------------------------|---------|\n| `value`          | `string`                  | Initial query value                     | `\"\"`    |\n| `placeholder`    | `string`                  | Input placeholder text                  | `\"\"`    |\n| `className`      | `string`                  | Additional CSS classes                  | `\"\"`    |\n| `onChange`       | `(value: string) =\u003e void` | Called when the query input changes     | `-`     |\n| `onEnter`        | `(value: string) =\u003e void` | Called when the user presses Enter      | `-`     |\n| `onInvalidQuery` | `(error: string) =\u003e void` | Called when an invalid query is entered | `-`     |\n\n### QuerityBuilderUI\n\n`QuerityBuilderUI` is a component that provides a user interface for building queries. \n\nIt includes all the necessary components to create a query in a visual way, including filters, sorting, and pagination.\n\nHere's how it looks (with default theme, see [Provider \u0026 Styling](#provider--styling)):\n\n![QuerityBuilderUI](/assets/querity-builder-ui.png)\n\n#### Usage\n\n```tsx\nimport { QuerityBuilderUI } from \"@queritylib/react\";\n\n\u003cQuerityBuilderUI\n  query={query}\n  onChange={(q) =\u003e console.log('Query updated', q)}\n  className=\"custom-class\"\n/\u003e\n```\n\n#### Props\n\n| Prop        | Type                      | Description                      | Default |\n|-------------|---------------------------|----------------------------------|---------|\n| `query`     | `QuerityQuery`            | Initial query object             | `-`     |\n| `onChange`  | `(query: string) =\u003e void` | Called when the query is updated | `-`     |\n| `className` | `string`                  | Additional CSS classes           | `-`     |\n\n## Utilities\n\n### QuerityParser\n\n`QuerityParser` is a utility for parsing and validating the Querity query language. It provides methods to check the validity of a query and to parse it into a structured format.\n\n#### Usage\n\n```tsx\nimport { QuerityParser } from \"@queritylib/react\";\n\ntry {\n  const input = 'lastName=\"Skywalker\" sort by firstName page 1,10'\n  const query = QuerityParser.parseQuery(input)\n  console.log(query)\n  /*\n  {\n    filter: {\n      propertyName: \"lastName\", \n      operator: Operator.EQUALS, \n      value: \"Skywalker\"\n    }, \n    sort: [{\n      propertyName: \"firstName\", \n      direction: Direction.ASC\n    }], \n    pagination: {\n      page: 1, \n      size: 10\n    }, \n    distinct: false\n  }\n  */\n} catch (e) {\n  console.log('Query parsing error', e)\n}\n```\n\n### QuerityBuilder\n\n`QuerityBuilder` is a utility for building query string from a structured format. It provides methods to convert a query object into a string representation.\n\n#### Usage\n\n```tsx\nimport { QuerityBuilder, Query, Operator } from \"@queritylib/react\";\n\nconst queryObj: Query = {\n  filter: { propertyName: \"lastName\", operator: Operator.EQUALS, value: \"Skywalker\" }\n}\nconst queryStr = QuerityBuilder.buildQuery(queryObj)\nconsole.log(queryStr)\n// lastName=\"Skywalker\"\n```\n\n## Development\n\nTo make changes to the components in this library and test them in a real application, we strongly suggest to use \n`npm link` to link the library to your local environment and use it into the [Querity Demo](https://github.com/queritylib/querity-demo) frontend.\n\nTo do this, follow these steps:\n\n```shell\nnpm link # in the library directory\n\nnpm link @queritylib/react # in the Querity Demo frontend directory\n```\n\n## Contributing\n\nWe welcome contributions! If you’d like to improve this library, feel free to submit a pull request or open an issue.\n\n## License\n\nThis project is licensed under the Apache-2.0 License. See the [LICENSE](LICENSE) file for details.\n\n---\n\nFor any questions or feedback, please reach out via the [GitHub repository](https://github.com/queritylib/querity-react).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqueritylib%2Fquerity-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqueritylib%2Fquerity-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqueritylib%2Fquerity-react/lists"}