/help/faq/collections.en
Type: /type/page
body: value: Collections are another way of showcasing books on a theme or subject. While [lists](https://openlibrary.org/lists) allow you to add a book from the book's page, [collections](https://openlibrary.org/collections/) are created by writing a small amount of code for a **carousel** in a new collection page. You must be a curator to create or edit collections.

This is an example carousel: 

{{QueryCarousel('subject:"1000blackgirlbooks"')}}

## Table of Contents

1. <a href="#permissions">Check Your Permissions</a>
2. <a href="#organize">Organize the Collection</a>
3. <a href="#carousels">Build the Carousels</a>
4. <a href="#finish-page">Finish the Collection Page</a>
5. <a href="#add-link">Add a Link to the Collection</a>

<h2 id="permissions">1. Check Your Permissions</h2>

**Creating a collection is currently a curator-only feature,** so your user account will need to have the correct `curator` permissions to create and edit collection pages. To find out if your account has the permissions, first log into the Open Library site. Then visit the <a href="https://openlibrary.org/collections">Collections page</a> and click on the 'Edit' button. If the page opens up with a text box that you can edit, click 'cancel' at the bottom. Your account has permissions and you can go on to <a href="#organize">step 2</a>. 

However, if you see a "permission denied" message, your account doesn't have the curator permissions. To become a curator, check out our pages about <a href="https://openlibrary.org/volunteer">volunteering as a librarian</a> and <a href="https://openlibrary.org/librarians">librarianship</a>. When you email us, please tell us that you're interested in creating collections. 

If you're already contributing as a librarian and you ought to have (or would like!) curator permissions, please reach out on Slack!  

In the meantime, anyone can start preparing a collection by creating lists, cleaning up the work records, adding cover images, and thinking about organizing their collection.

<h2 id="organize">2. Organize the Collection Page</h2>

Collection pages are the sort of pages that go viral, so it's good to think about a visitor arriving at a collection's page with an interest in the subject but without knowing anything about Open Library. 

Collection pages usually have
1. an eye-catching header graphic
2. some introductory text explaining the collection's subject and how to borrow a book with a free account
3. a table of contents, if the collection is big enough
4. carousels full of books!

However! These are just ideas. The carousels are the only required part of a collection page, so you can design your page  any way you want. 

All collections are linked from the [Collections](https://openlibrary.org/collections) page, so you can see how other curators have arranged collections in many different ways.

- The [K-12 Student Library](https://openlibrary.org/collections/k-12) is arranged by grade and reading level. 
- The [Star Wars](https://openlibrary.org/collections/star-wars) collection is arranged chronologically by era, separated into the two 'Canon' and 'Legends' alternate universes. 
- The [July](https://openlibrary.org/collections/july) collection, like the other monthly collections, is arranged with carousels for each month-long observance, like National Grilling Month and National Family Fun Month.
- The [Rainbow Magic](https://openlibrary.org/collections/Rainbow_Magic) collection is arranged by the series, with lots of very short carousels.
- The [Newbery Medal Winners](https://openlibrary.org/collections/newbery-medal) are arranged by decade, and (like Rainbow Magic) are split into very short carousels.
- The [LGBTQ](https://openlibrary.org/collections/LGBTQ) collection is arranged by subject, fiction or non-fiction, and reader's age. It has very large carousels, some with more than a hundred books.
- The [Historia de España en viñetas](https://openlibrary.org/collections/cascaborra-historia-de-espana-en-vinetas) Spanish-language collection is arranged by historical era, from oldest to most recent.

If you have curator permissions, you can create a collection's page. If you don't have permission yet, you can begin with a document, like a google doc. Here's an example of the [Star Wars collection's Google doc](https://drive.google.com/file/d/1SReATm54ovOSNprXyeEj19IyRMAd1KCF/view), which [tmanarl](https://openlibrary.org/people/tmanarl) started before he had permissions. He created lists of works he wanted in the carousel, then sent the document to a curator who created the page for him, from his lists. You can compare his google doc to the [finished Star Wars collection page](https://openlibrary.org/collections/star-wars). 

### Name & Create the Collection Page

First, you'll need to decide on a collection name for both the title and the url. 

For example, "Newbery Medal Winners" is a title and "newbery-medal-winners" will go in the url.  You can use underscores and hyphens in the url, but no spaces. For example, any of these would work: `newbery-medal-winners`, `Newbery-Medal-Winners`, `Newbery_Medal_Winners`. 

If you don't have permissions, just note all this on your document.

First, create the new collection page by entering `https://openlibrary.org/collections/collection-name?m=edit` in your browser address bar, where `collection-name` should be replaced with the collection name used in the URL. Choose wisely. You may change the name on the collection page after it’s been created, but you can't change the URL.

Some example page urls and names are: 

- https://openlibrary.org/collections/star-wars (Star Wars)
- https://openlibrary.org/collections/newbery-medal (Newbery Medal Winners) 
- https://openlibrary.org/collections/july (July) 
- https://openlibrary.org/collections/LGBTQ (LGBTQ) 
- https://openlibrary.org/collections/Rainbow_Magic (Rainbow Magic) 
- https://openlibrary.org/collections/Marley-Dias-1000BlackGirlBooks-Library (Marley Dias Library #1000BlackGirlBooks)

### Keeping Track of the Collection Page

All pages created under the `collections/` directory will show up on the very bottom of the [Curated Collections](https://openlibrary.org/collections/) page, so you can find it while you're working on it. 

### Think About the Carousels

Each carousel loads the results of a search query. For tips on different kinds of Open Library search queries, [click here](https://openlibrary.org/search/howto). You can search by subject, place, person, language, and publisher, but you can't combine the queries in a carousel. 

If you want to fill a carousel with a specific set of works, there are two methods:

**By subject**
First, you can manually add a unique subject to those records. This is how the [LGBTQ](https://openlibrary.org/collections/LGBTQ) collection is arranged. When you build a carousel using a subject, you only have to edit the collection page when you create the carousel. Later, to add a work to the carousel, you can just add the subject to the work record. Since you're probably editing records anyway, to add covers and clean up descriptions, you can easily add the subject while you're in the record.

When adding a unique subject, the subject should begin with the prefix "collection:" and use underscores instead of spaces. For example, "collection:LGBTQ_history" or "collection:star_wars". This way, the subject's context is clear, the librarians will know the subject should not be moved or changed, and the format matches our other subjects such as "award:pulitzer_prize=fiction". 

**By Identifier**
Second, you can collect the work identifiers (in the form `OL...W`) and write them directly in the search query. This is how the [Star Wars](https://openlibrary.org/collections/star-wars) collection is arranged. The easiest way to collect the work identifiers is to create a <a href="https://openlibrary.org/lists">list of works</a>, one per carousel, and then use a script to create a carousel from the list automatically. 

**Important:** Carousels don't let you specify editions (`OL...M`) of works, so always click "use this work" when you add works to a list! 

To create a list, search for a work and find the green "Want to Read" button. Click the dropdown arrow, click "Use this Work," and either click "Create a new list" or add the work to an existing list by clicking on the list name.

### Editing & Merging Works

Creating a collection gives you a chance to clean up the related records. 

It's very common for records to have no description, no language, and/or no book cover. Carousels are eye-catching because of the book covers, so it's important to look up the ISBNs of editions without covers and try to find descriptions and covers. 

It's also common to find editions of a book spread across multiple identical works. To request those works to be merged, either reach out on Slack or submit the merge request [through the website](https://openlibrary.org/contact). 

For more about general librarian tasks, [click here](https://openlibrary.org/librarians).

<h2 id="carousels">3. Build the Carousels</h2>

For everything you need to know about carousels, with examples, [click here](https://openlibrary.org/help/faq/collections-carousel-examples). Have questions? Please ask!

If you're making a collection using search queries without needing any explicit work identifiers, you can skip to <a href="#finish-page">step 4</a>. 

### Turning Lists into Carousels

If you don't feel comfortable with scripting, you can send your document and/or your list to a curator or librarian and we'll create the carousels for you. 

Once you have a list of works, you can get the list of identifiers from the JSON export. 

Every list has a JSON export that includes the identifiers of every entry in the list. For example, the [Lambda Literary Awards](https://openlibrary.org/people/jehanni/lists/OL197731L/Lambda_Literary_Awards) list has a [JSON export](https://openlibrary.org/people/jehanni/lists/OL197731L/Lambda_Literary_Awards/export?format=json) with the identifiers in the `entries` array.  You can also scroll down to the bottom of a list's page and click on the JSON export manually.

However, the easiest way is to to get the list of the IDs quickly is to go to the list page in your browser and open the developer tools console. 

If your list contains works only, run this code: 

    var seeds = await fetch('https://openlibrary.org/people/USERNAME/lists/LISTID/seeds.json')  
    .then(r => r.json());  
    seeds.entries.map(e => e.url).join(' OR ');

If it contains both works and editions, run this code:

    var urls = [];
    var promises = [];
    var seeds = await fetch('https://openlibrary.org/people/USERNAME/lists/LISTID/seeds.json').then(r => r.json());
    seeds.entries.forEach((item) => {
        if(item.type === 'work') urls.push(item.url);
        else if(item.type === 'edition') {
            promises.push(fetch(item.url+'.json')
                .then(r => r.json())
                .then((record) => {
                    urls.push(record.works[0].key);
                })
            );
        }
        else console.warn('garbage', item);
    })
    Promise.all(promises).then(() => urls.join(' OR '));

Copy the list of IDs and paste it into your carousel.

<h2 id="finish-page">4. Finish the Collection Page</h2>

Collections can take a lot of work and feel very personal to a curator, so it's best not to edit other collections pages without talking with the curator first. However, feel free to click 'Edit' on other collections pages so you can see how the introduction, table of contents, and other carousels were created. Feel free to copy language and code!

For two different approaches to introductions, check out the [LGBTQ](https://openlibrary.org/collections/LGBTQ) and [Star Wars](https://openlibrary.org/collections/star-wars) collections. And, of course, you don't have to write any introduction at all if you don't want to.

There's a glitch at the moment where not all borrowable editions are showing up in the carousels, so it might be helpful to add the following:

    You can read or borrow a book if the bar underneath the cover says "Borrow" or "Read." **If a book says it is "not in library" or "checked out," a copy might still be available!** Click on the book's cover to see if you can borrow one of the other editions.

<h2 id="add-link">5. Add a Link to the Collection</h2>

The time has come! Your collection page exists, your introduction is fantastic, and the carousels look great. It's time to add a link on the [Curated Collections](https://openlibrary.org/collections/) page. 

First, decide where you want to put your link. Then, click 'Edit', add your link exactly like the other links, and click 'Save'. 

Next, spread the word! Give the link to your friends! Tell us about it! We want to share it far and wide!
title: How to Create Curated Collections
m: edit