{"id":1991,"date":"2026-04-09T07:09:17","date_gmt":"2026-04-08T23:09:17","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=1991"},"modified":"2026-03-28T04:07:54","modified_gmt":"2026-03-28T04:07:54","slug":"how-to-use-applicationgetcustomlistnum-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-applicationgetcustomlistnum-in-the-xlwings-api-way\/","title":{"rendered":"How to use Application.GetCustomListNum in the xlwings API way"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">The <code>GetCustomListNum<\/code> member of the <code>Application<\/code> object in Excel is a method used to retrieve the index number of a custom list that has been defined in the Excel application. Custom lists are often utilized for sorting data in a user-defined order, such as days of the week or months, and they can also be used in functions like <code>MATCH<\/code> or <code>VLOOKUP<\/code> to align data with these custom sequences. In xlwings, this functionality is accessible through the <code>api<\/code> property, which provides direct access to the underlying Excel object model. This method is particularly useful when you need to programmatically determine the position of a specific list within Excel&#8217;s custom list collection, enabling dynamic interactions with list-based operations.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Functionality<\/strong><br><code>GetCustomListNum<\/code> returns a numeric value representing the index of a custom list based on a provided list array. If the specified list matches one of the custom lists defined in Excel, the method returns its index number (starting from 1 for the first custom list). If no match is found, it returns <code>0<\/code>. This can assist in validating or identifying custom lists before performing operations like sorting or data alignment.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Syntax<\/strong><br>In xlwings, the method is called via the <code>Application<\/code> object. The syntax is:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>index = xw.apps&#91;0].api.GetCustomListNum(list_array)<\/code><\/pre>\n\n\n\n<ul class=\"wp-block-list\">\n<li><code>list_array<\/code>: This is a required parameter that specifies the list to be checked. It should be passed as an array or range of values. In xlwings, you can use a Python list or an Excel range object. For example, a Python list like <code>[\"Mon\", \"Tue\", \"Wed\"]<\/code> or an xlwings range like <code>sheet.range(\"A1:A3\").value<\/code>.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Parameters and Values<\/strong><br>The <code>list_array<\/code> parameter must be a one-dimensional array of strings or numbers that correspond to the custom list entries in Excel. Excel stores custom lists in a specific order, and the method compares the input array to these stored lists. Note that custom lists are case-insensitive in Excel, so the matching process ignores letter case. If the input array is empty or invalid, the method may return an error or <code>0<\/code>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Code Examples<\/strong><br>Here are some xlwings API code instances demonstrating the use of <code>GetCustomListNum<\/code>:<\/p>\n\n\n\n<ol class=\"wp-block-list\">\n<li><strong>Basic Example with a Python List<\/strong>: Check if a custom list for weekdays exists and get its index.<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\n\n# Connect to the active Excel instance\napp = xw.apps.active\n\n# Define a list to check (e.g., weekdays)\nlist_to_check = &#91;\"Monday\", \"Tuesday\", \"Wednesday\", \"Thursday\", \"Friday\"]\n\n# Get the custom list index\nlist_index = app.api.GetCustomListNum(list_to_check)\nprint(f\"The custom list index is: {list_index}\")\n# Output might be 1 if this is the first custom list, or 0 if not found.<\/code><\/pre>\n\n\n\n<ol start=\"2\" class=\"wp-block-list\">\n<li><strong>Using an Excel Range as Input<\/strong>: Retrieve data from a worksheet and check if it matches a custom list.<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\n\n# Open a workbook and reference a sheet\nwb = xw.Book(\"example.xlsx\")\nsheet = wb.sheets&#91;\"Sheet1\"]\n\n# Get values from a range (e.g., cells A1:A5)\nrange_values = sheet.range(\"A1:A5\").value\n\n# Ensure it's a flat list (xlwings returns a list of lists for 2D ranges)\nif isinstance(range_values&#91;0], list):\n    range_values = &#91;item for sublist in range_values for item in sublist]\n\n# Check for custom list match\napp = xw.apps.active\nlist_index = app.api.GetCustomListNum(range_values)\nif list_index > 0:\n    print(f\"Custom list found at index: {list_index}\")\nelse:\n    print(\"No matching custom list found.\")<\/code><\/pre>\n\n\n\n<ol start=\"3\" class=\"wp-block-list\">\n<li><strong>Dynamic List Validation<\/strong>: Before sorting data, verify that a custom list exists to avoid errors.<\/li>\n<\/ol>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\n\napp = xw.apps.active\ncustom_list = &#91;\"Low\", \"Medium\", \"High\"] # Example priority list\n\nindex = app.api.GetCustomListNum(custom_list)\nif index == 0:\nprint(\"Warning: Custom list not defined. Consider adding it in Excel options.\")\nelse:\n# Proceed with sorting or other operations using the list index\nprint(f\"Using custom list index {index} for sorting.\")<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>The `GetCustomListNum` member of the `Application` object in Excel is a method used to retrieve the &#8230;<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[25],"tags":[],"class_list":["post-1991","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/1991","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/comments?post=1991"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/1991\/revisions"}],"predecessor-version":[{"id":3033,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/1991\/revisions\/3033"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=1991"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=1991"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=1991"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}