COL-Users

Download

col-users@lists.gbif.org

May 2026

2 participants
1 discussions

portal-components v2 released - breaking changes, please pin your version
by Markus Döring 30 May '26

30 May '26

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-bro…"></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]

2 2