{"id":1970,"date":"2026-03-29T15:45:16","date_gmt":"2026-03-29T07:45:16","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=1970"},"modified":"2026-03-28T03:33:15","modified_gmt":"2026-03-28T03:33:15","slug":"how-to-use-applicationaddcustomlist-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-applicationaddcustomlist-in-the-xlwings-api-way\/","title":{"rendered":"How to use Application.AddCustomList in the xlwings API way"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">The <code>AddCustomList<\/code> member of the <code>Application<\/code> object in Excel is a method that allows you to define a custom list for sorting and auto-filling data. Custom lists are particularly useful for creating personalized sorting orders, such as days of the week, months, or any user-defined sequence, which can then be applied across worksheets to ensure consistent data organization. In xlwings, this functionality is accessed through the <code>api<\/code> property, which provides direct access to the underlying Excel object model, enabling precise control over Excel&#8217;s features from Python.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Functionality:<\/strong><br>The primary function of <code>AddCustomList<\/code> is to add a new custom list to Excel&#8217;s memory. Once added, this list can be used in sorting operations or for auto-fill actions, where dragging a cell&#8217;s fill handle will populate cells based on the defined sequence. This is beneficial for standardizing data entry and maintaining order in datasets that follow non-alphabetical or non-numeric sequences.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Syntax in xlwings:<\/strong><br>The xlwings API call follows the pattern:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>app.api.AddCustomList(ListArray, ByRow)<\/code><\/pre>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>ListArray<\/strong>: This parameter specifies the items to be included in the custom list. It can be provided as a Python list or tuple containing strings or numbers. For example, <code>['Low', 'Medium', 'High']<\/code> or <code>('Q1', 'Q2', 'Q3', 'Q4')<\/code>. The list must be one-dimensional.<\/li>\n\n\n\n<li><strong>ByRow<\/strong>: This is a Boolean parameter that indicates whether the list is arranged by rows. In most cases, setting <code>ByRow<\/code> to <code>False<\/code> is appropriate, as custom lists are typically column-oriented. If set to <code>True<\/code>, the list is interpreted as a row-based array, but this is less common. The default behavior in Excel VBA is <code>False<\/code>, and it is generally recommended to use <code>False<\/code> in xlwings unless specific row-based data is provided.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Example Usage:<\/strong><br>Below is an xlwings code example that demonstrates how to add a custom list and then use it for sorting data in an Excel worksheet. This example assumes an existing Excel workbook is open via xlwings.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\n\n# Connect to the active Excel application\napp = xw.apps.active\n\n# Define a custom list for priority levels\ncustom_list = &#91;'Low', 'Medium', 'High']\n\n# Add the custom list using the Application object's AddCustomList method\napp.api.AddCustomList(ListArray=custom_list, ByRow=False)\n\n# Now, use the custom list to sort data in a specific worksheet\nwb = xw.books.active\nws = wb.sheets&#91;'Sheet1']\n\n# Assume column A contains priority data to be sorted based on the custom list\n# Set the sort range (e.g., A1:A10)\nsort_range = ws.range('A1:A10')\n\n# Apply sorting with the custom order\nsort_range.api.Sort(\nKey1=ws.range('A1').api,\nOrder1=1, # Ascending order\nCustomOrder=custom_list&#91;0], # Use the first item of the list to reference the custom list\nDataOption1=0\n)\n\n# Note: In Excel, the custom list is stored globally, so it can be reused across workbooks during the session.<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>The `AddCustomList` member of the `Application` object in Excel is a method that allows you to defin&#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-1970","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/1970","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=1970"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/1970\/revisions"}],"predecessor-version":[{"id":2998,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/1970\/revisions\/2998"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=1970"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=1970"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=1970"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}