portal-components v2 released - breaking changes, please pin your version
Dear all, We have just released version 2 of the Catalogue of Life portal-components (the col-browser ReactJS library many of you embed to show ChecklistBank trees, search forms, taxon pages and citations on your own sites). This is a major, breaking release, so it needs a moment of your attention. If you do nothing else, read this: anyone currently loading the components from a @latest URL should switch to a pinned @1 URL now. v1 is unchanged and stays in maintenance mode, so pinning to it keeps your existing pages working exactly as before: <script src="https://cdn.jsdelivr.net/gh/CatalogueOfLife/portal-components@1/umd/col-browser.min.js"></script> <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/CatalogueOfLife/portal-components@1/umd/main.css"> The @latest selector now resolves to v2 and will silently move you to v3 whenever that lands, so we recommend pinning to a major (@1 or @2) on every page rather than tracking @latest. What changed in v2. The stack is now current (React 19, Ant Design 6), and every component is fully controlled - the library no longer reads or writes the page URL itself. In practice that means embedders update three things: drop the separate React/ReactDOM <script> tags (v2 bundles React 19 and re-exposes it as ColBrowser.React / ColBrowser.ReactDOM), mount via createRoot instead of ReactDOM.render, and supply navigation as props. A couple of names also changed: catalogueKey -> datasetKey, and the source-dataset components Dataset / DatasetSearch -> SourceDataset / SourceDatasetList. To make the wiring painless there is a built-in withRouting adapter that reconnects components to the URL from a single paths map, so most static-site embeds are a few lines. The full upgrade guide, prop tables and copy-paste snippets are in the README: https://github.com/CatalogueOfLife/portal-components#upgrading-from-1x-to-20 We'd encourage you to upgrade to v2. Decoupling navigation from the URL makes the components far more flexible - they now drop cleanly into static portals, react-router, Next.js or any custom router without fighting the library, and you control link shapes and routing entirely from props. Two components worth a look. v2 ships a new standalone TaxonDistribution map: an interactive MapLibre GL vector map of a taxon's distribution polygons, with an optional GBIF occurrence overlay layered on top - so you can show curated CoL distributions alongside live GBIF occurrence data on any page. For species you can even include all subspecies distributions as separate layers, see the attached screenshot at the end. We have also exposed the TaxonBreakdown as a standalone component for reuse: a click-to-drill Highcharts donut that breaks a taxon's accepted children down by rank (one or two levels), handy for dashboards and group-summary pages. The map only renders areas it can resolve to a geometry, which is a good moment to flag the col-gazetteers project. It collects the area geometries CoL serves - ISO countries & their subregions, TDWG areas, FAO Major Fishing Areas, IHO Sea Areas, MRGID MarineRegions from VLIZ and more - and you can browse and render them all on this site: https://catalogueoflife.github.io/col-gazetteers/ If you publish distributions in your own datasets, we'd strongly encourage you to provide them as structured distributions using areaID values drawn from one of these standard gazetteers (TDWG, ISO, FAO, IHO, MRGID, TEOW, ...) together with the matching gazetteer, rather than as free text. Structured areas are what let the map draw your data and let it line up across datasets. The COLDP distribution fields are documented here: https://github.com/CatalogueOfLife/coldp/blob/master/README.md#distribution You can try every component live against the production ChecklistBank API on the demo page: https://catalogueoflife.github.io/portal-components/ Also new on the portal. There's a new metrics page worth a look - it shows the size of the selected release and a timeline of how COL has grown over the years: https://www.catalogueoflife.org/data/metrics Looking ahead. We are about to migrate the Catalogue of Life portal to Astro, a static-site generator that is a much better fit for these React components than our current setup. This shouldn't affect how you embed the components, but it's the reason v2 was reworked to be host-agnostic, and it should make the portal itself faster and easier to maintain. More on that soon. Best regards, Markus Catalogue of Life [cid:221f65b3-fa2e-4f1e-86f3-e07e48fbbfb5@eurprd09.prod.outlook.com]
Dear Markus, I have already comments from a user: The manually curated distribution of the various taxa has been eliminated. This is a pity, because distribution data were very useful and most often were correct and comprehensive. For a few taxa, some incorrect distribution data are now provided through links to GBIF distribution records, but those data are almost always wrong as the GBIF database is based on largely misidentified material, and not on data provided in the original papers. Kind regards Paul Schoolmeesters Langeveldstraat, 23 3020 Herent Belgium From: Markus Döring via COL-Users <col-users@lists.gbif.org> Sent: vrijdag 29 mei 2026 18:27 To: col-users@lists.gbif.org Cc: Markus Döring <mdoering@gbif.org> Subject: [COL-Users] portal-components v2 released - breaking changes, please pin your version Dear all, We have just released version 2 of the Catalogue of Life portal-components (the col-browser ReactJS library many of you embed to show ChecklistBank trees, search forms, taxon pages and citations on your own sites). This is a major, breaking release, so it needs a moment of your attention. If you do nothing else, read this: anyone currently loading the components from a @latest URL should switch to a pinned @1 URL now. v1 is unchanged and stays in maintenance mode, so pinning to it keeps your existing pages working exactly as before: <script src="https://cdn.jsdelivr.net/gh/CatalogueOfLife/portal-components@1/umd/col -browser.min.js <https://cdn.jsdelivr.net/gh/CatalogueOfLife/portal-components@1/umd/col-bro wser.min.js%22%3e%3c/script> "></script> <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/CatalogueOfLife/portal-components@1/umd/ma in.css"> The @latest selector now resolves to v2 and will silently move you to v3 whenever that lands, so we recommend pinning to a major (@1 or @2) on every page rather than tracking @latest. What changed in v2. The stack is now current (React 19, Ant Design 6), and every component is fully controlled - the library no longer reads or writes the page URL itself. In practice that means embedders update three things: drop the separate React/ReactDOM <script> tags (v2 bundles React 19 and re-exposes it as ColBrowser.React / ColBrowser.ReactDOM), mount via createRoot instead of ReactDOM.render, and supply navigation as props. A couple of names also changed: catalogueKey -> datasetKey, and the source-dataset components Dataset / DatasetSearch -> SourceDataset / SourceDatasetList. To make the wiring painless there is a built-in withRouting adapter that reconnects components to the URL from a single paths map, so most static-site embeds are a few lines. The full upgrade guide, prop tables and copy-paste snippets are in the README: https://github.com/CatalogueOfLife/portal-components#upgrading-from-1x-to-20 We'd encourage you to upgrade to v2. Decoupling navigation from the URL makes the components far more flexible - they now drop cleanly into static portals, react-router, Next.js or any custom router without fighting the library, and you control link shapes and routing entirely from props. Two components worth a look. v2 ships a new standalone TaxonDistribution map: an interactive MapLibre GL vector map of a taxon's distribution polygons, with an optional GBIF occurrence overlay layered on top - so you can show curated CoL distributions alongside live GBIF occurrence data on any page. For species you can even include all subspecies distributions as separate layers, see the attached screenshot at the end. We have also exposed the TaxonBreakdown as a standalone component for reuse: a click-to-drill Highcharts donut that breaks a taxon's accepted children down by rank (one or two levels), handy for dashboards and group-summary pages. The map only renders areas it can resolve to a geometry, which is a good moment to flag the col-gazetteers project. It collects the area geometries CoL serves - ISO countries & their subregions, TDWG areas, FAO Major Fishing Areas, IHO Sea Areas, MRGID MarineRegions from VLIZ and more - and you can browse and render them all on this site: https://catalogueoflife.github.io/col-gazetteers/ If you publish distributions in your own datasets, we'd strongly encourage you to provide them as structured distributions using areaID values drawn from one of these standard gazetteers (TDWG, ISO, FAO, IHO, MRGID, TEOW, ...) together with the matching gazetteer, rather than as free text. Structured areas are what let the map draw your data and let it line up across datasets. The COLDP distribution fields are documented here: https://github.com/CatalogueOfLife/coldp/blob/master/README.md#distribution You can try every component live against the production ChecklistBank API on the demo page: https://catalogueoflife.github.io/portal-components/ Also new on the portal. There's a new metrics page worth a look - it shows the size of the selected release and a timeline of how COL has grown over the years: https://www.catalogueoflife.org/data/metrics Looking ahead. We are about to migrate the Catalogue of Life portal to Astro, a static-site generator that is a much better fit for these React components than our current setup. This shouldn't affect how you embed the components, but it's the reason v2 was reworked to be host-agnostic, and it should make the portal itself faster and easier to maintain. More on that soon. Best regards, Markus Catalogue of Life
Dear Paul, no manually curated distribution data has been eliminated. It is and has always been just very patchy and many sources have not been tracking distributions at all. GBIF data obviously is not perfect. There are wrong records and bad identifications in there. But it does give a good first indication. If you don't like to use it ignore it, you can also turn it off in the map layer. I will soon work on storing such user settings so you can turn off GBIF layers once and forever. Best, Markus On 30. May 2026, at 10:45, Paul Schoolmeesters via COL-Users <col-users@lists.gbif.org> wrote: Dear Markus, I have already comments from a user: The manually curated distribution of the various taxa has been eliminated. This is a pity, because distribution data were very useful and most often were correct and comprehensive. For a few taxa, some incorrect distribution data are now provided through links to GBIF distribution records, but those data are almost always wrong as the GBIF database is based on largely misidentified material, and not on data provided in the original papers. Kind regards Paul Schoolmeesters Langeveldstraat, 23 3020 Herent Belgium From: Markus Döring via COL-Users <col-users@lists.gbif.org<mailto:col-users@lists.gbif.org>> Sent: vrijdag 29 mei 2026 18:27 To: col-users@lists.gbif.org<mailto:col-users@lists.gbif.org> Cc: Markus Döring <mdoering@gbif.org<mailto:mdoering@gbif.org>> Subject: [COL-Users] portal-components v2 released - breaking changes, please pin your version Dear all, We have just released version 2 of the Catalogue of Life portal-components (the col-browser ReactJS library many of you embed to show ChecklistBank trees, search forms, taxon pages and citations on your own sites). This is a major, breaking release, so it needs a moment of your attention. If you do nothing else, read this: anyone currently loading the components from a @latest URL should switch to a pinned @1 URL now. v1 is unchanged and stays in maintenance mode, so pinning to it keeps your existing pages working exactly as before: <script src="https://cdn.jsdelivr.net/gh/CatalogueOfLife/portal-components@1/umd/col-browser.min.js"></script<https://cdn.jsdelivr.net/gh/CatalogueOfLife/portal-components@1/umd/col-browser.min.js%22%3e%3c/script>> <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/CatalogueOfLife/portal-components@1/umd/main.css"> The @latest selector now resolves to v2 and will silently move you to v3 whenever that lands, so we recommend pinning to a major (@1 or @2) on every page rather than tracking @latest. What changed in v2. The stack is now current (React 19, Ant Design 6), and every component is fully controlled - the library no longer reads or writes the page URL itself. In practice that means embedders update three things: drop the separate React/ReactDOM <script> tags (v2 bundles React 19 and re-exposes it as ColBrowser.React / ColBrowser.ReactDOM), mount via createRoot instead of ReactDOM.render, and supply navigation as props. A couple of names also changed: catalogueKey -> datasetKey, and the source-dataset components Dataset / DatasetSearch -> SourceDataset / SourceDatasetList. To make the wiring painless there is a built-in withRouting adapter that reconnects components to the URL from a single paths map, so most static-site embeds are a few lines. The full upgrade guide, prop tables and copy-paste snippets are in the README: https://github.com/CatalogueOfLife/portal-components#upgrading-from-1x-to-20 We'd encourage you to upgrade to v2. Decoupling navigation from the URL makes the components far more flexible - they now drop cleanly into static portals, react-router, Next.js or any custom router without fighting the library, and you control link shapes and routing entirely from props. Two components worth a look. v2 ships a new standalone TaxonDistribution map: an interactive MapLibre GL vector map of a taxon's distribution polygons, with an optional GBIF occurrence overlay layered on top - so you can show curated CoL distributions alongside live GBIF occurrence data on any page. For species you can even include all subspecies distributions as separate layers, see the attached screenshot at the end. We have also exposed the TaxonBreakdown as a standalone component for reuse: a click-to-drill Highcharts donut that breaks a taxon's accepted children down by rank (one or two levels), handy for dashboards and group-summary pages. The map only renders areas it can resolve to a geometry, which is a good moment to flag the col-gazetteers project. It collects the area geometries CoL serves - ISO countries & their subregions, TDWG areas, FAO Major Fishing Areas, IHO Sea Areas, MRGID MarineRegions from VLIZ and more - and you can browse and render them all on this site: https://catalogueoflife.github.io/col-gazetteers/ If you publish distributions in your own datasets, we'd strongly encourage you to provide them as structured distributions using areaID values drawn from one of these standard gazetteers (TDWG, ISO, FAO, IHO, MRGID, TEOW, ...) together with the matching gazetteer, rather than as free text. Structured areas are what let the map draw your data and let it line up across datasets. The COLDP distribution fields are documented here: https://github.com/CatalogueOfLife/coldp/blob/master/README.md#distribution You can try every component live against the production ChecklistBank API on the demo page: https://catalogueoflife.github.io/portal-components/ Also new on the portal. There's a new metrics page worth a look - it shows the size of the selected release and a timeline of how COL has grown over the years: https://www.catalogueoflife.org/data/metrics Looking ahead. We are about to migrate the Catalogue of Life portal to Astro, a static-site generator that is a much better fit for these React components than our current setup. This shouldn't affect how you embed the components, but it's the reason v2 was reworked to be host-agnostic, and it should make the portal itself faster and easier to maintain. More on that soon. Best regards, Markus Catalogue of Life <image001.png> _______________________________________________ COL-Users mailing list -- col-users@lists.gbif.org<mailto:col-users@lists.gbif.org> To unsubscribe send an email to col-users-leave@lists.gbif.org<mailto:col-users-leave@lists.gbif.org>
participants (2)
-
Markus Döring -
schoolp＠skynet.be