Work with lists

The Google Docs API supports converting plain paragraphs to bulleted lists and removing bullets from paragraphs.

Convert a paragraph to a list

A common paragraph formatting operation is converting paragraphs into a bulleted list.

To create a list, use the documents.batchUpdate method and supply a CreateParagraphBulletsRequest. Include a Range to specify the affected cells and a BulletGlyphPreset to set the pattern for the bullet.

All paragraphs that overlap with the given range are bulleted. If the specified range overlaps with a table, the bullets are applied within the table cells. The nesting level of each paragraph is determined by counting leading tabs in front of each paragraph.

You can't adjust the nesting level of an existing bullet. Instead, you must delete the bullet, set the leading tabs in front of the paragraph, and then create the bullet again. For more information, see Remove bullets from a list.

You can also use CreateParagraphBulletsRequest to change the bullet style for an existing list.

The following code sample shows a batch request that first inserts text at the start of the document, and then it creates a list from the paragraphs spanning the first 50 characters. The BulletGlyphPreset uses BULLET_ARROW_DIAMOND_DISC which means the first three nesting levels of the bulleted list are represented by an arrow, a diamond, and a disc.

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Item One\n")
        .setLocation(new Location().setIndex(1).setTabId(TAB_ID))));

requests.add(new Request().setCreateParagraphBullets(
        new CreateParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(50)
                        .setTabId(TAB_ID))
                .setBulletPreset("BULLET_ARROW_DIAMOND_DISC")));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
        .batchUpdate(DOCUMENT_ID, body).execute();

Python

requests = [
        {
        'insertText': {
            'location': {
                'index': 1,
                'tabId': TAB_ID
            },
            'text': 'Item One\n',
        }}, {
        'createParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex':  50,
                'tabId': TAB_ID
            },
            'bulletPreset': 'BULLET_ARROW_DIAMOND_DISC',
        }
    }
]

result = service.documents().batchUpdate(
    documentId=DOCUMENT_ID, body={'requests': requests}).execute()

Figure 1. Convert a paragraph to a list.

Remove bullets from a list

To remove bullets from a paragraph list, use the documents.batchUpdate method and supply a DeleteParagraphBulletsRequest. Include a Range to specify the affected cells.

The method deletes all bullets that overlap with the given range, regardless of nesting level. To visually preserve the nesting level, indentation is added to the start of each corresponding paragraph.

The following code sample shows a batch request that deletes bullets from a paragraph list.

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setDeleteParagraphBullets(
        new DeleteParagraphBulletsRequest()
                .setRange(new Range()
                        .setStartIndex(1)
                        .setEndIndex(50)
                        .setTabId(TAB_ID))));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
        .batchUpdate(DOCUMENT_ID, body).execute();

Python

requests = [
        {
        'deleteParagraphBullets': {
            'range': {
                'startIndex': 1,
                'endIndex':  50,
                'tabId': TAB_ID
            },
        }
    }
]

result = service.documents().batchUpdate(
    documentId=DOCUMENT_ID, body={'requests': requests}).execute()