{"id":5190,"library":"django-multiselectfield","title":"Django Multiple Select Field","description":"django-multiselectfield provides new model and form fields for Django, allowing users to select multiple options from a predefined list. The selected values are stored in the database as a CharField containing comma-separated values. The current version is 1.0.1, and the project has an irregular release cadence, with a significant 1.0.0 release in June 2025 that introduced breaking changes.","status":"active","version":"1.0.1","language":"en","source_language":"en","source_url":"https://github.com/goinnn/django-multiselectfield","tags":["django","forms","fields","multiselect","model-field"],"install":[{"cmd":"pip install django-multiselectfield","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"This is a Django app, requiring Django 3.2+ for full compatibility.","package":"Django","optional":false}],"imports":[{"note":"Used for creating model fields that allow multiple selections.","symbol":"MultiSelectField","correct":"from multiselectfield import MultiSelectField"},{"note":"Introduced in v1.0.0 for sortable multi-select fields; requires jQuery and jQuery UI.","symbol":"SortMultiSelectField","correct":"from multiselectfield import SortMultiSelectField"}],"quickstart":{"code":"from django.db import models\nfrom multiselectfield import MultiSelectField\n\n# In your settings.py, ensure 'multiselectfield' is in INSTALLED_APPS\n# INSTALLED_APPS = [\n#     # ...\n#     'multiselectfield',\n#     # ...\n# ]\n\nMY_CHOICES = (\n    ('item_key1', 'Item title 1.1'),\n    ('item_key2', 'Item title 1.2'),\n    ('item_key3', 'Item title 1.3'),\n    ('item_key4', 'Item title 1.4'),\n    ('item_key5', 'Item title 1.5')\n)\n\nclass MyModel(models.Model):\n    my_field = MultiSelectField(choices=MY_CHOICES, default=['item_key1', 'item_key5'])\n    my_field_with_limits = MultiSelectField(\n        choices=MY_CHOICES,\n        min_choices=2,\n        max_choices=3,\n        max_length=100 # Adjust max_length based on expected comma-separated string length\n    )\n\n    def __str__(self):\n        return f\"{self.my_field} - {self.my_field_with_limits}\"\n\n# After defining your model, run:\n# python manage.py makemigrations\n# python manage.py migrate","lang":"python","description":"To use `MultiSelectField`, define your choices as a tuple of tuples. Add `multiselectfield` to your `INSTALLED_APPS` and then define a model field using `MultiSelectField`. Remember to run `makemigrations` and `migrate`."},"warnings":[{"fix":"Remove any references to `MSFList` or `MSFFlatchoices` from your code. If you were using them for `list_display`, consider using `get_FOO_display` method on your model or a custom admin method.","message":"Version 1.0.0 removed `MSFList` and `MSFFlatchoices`. These classes were intended for `admin.list_display` but never functioned correctly.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure all choices provided to `MultiSelectField` are string-based. For example, use `(('1', 'Item 1'), ('2', 'Item 2'))` instead of `((1, 'Item 1'), (2, 'Item 2'))`.","message":"As of version 1.0.0, integer choices are no longer supported. `MultiSelectField` inherits from `CharField`, and it's impossible to reliably distinguish between integer `1` and string `'1'` upon retrieval from the database.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use a custom method on your `ModelAdmin` or the `get_FOO_display` method on your model to format the output for `list_display`. Example: `list_display = ('get_my_field_display',)` in `ModelAdmin` where `get_my_field_display` is a method on the model.","message":"Adding a `MultiSelectField` directly to `list_display` in Django admin might not render as expected (e.g., showing a raw comma-separated string).","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure jQuery and jQuery UI are loaded in your templates when using `SortMultiSelectField` outside of the default Django admin forms. In the admin, you might need to explicitly include them in your `ModelAdmin`'s `form` definition or `change_form.html`.","message":"The `SortMultiSelectField` (introduced in v1.0.0) requires jQuery and jQuery UI to function correctly in the browser. These libraries are typically included in the Django admin interface.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `blank=True, default=''` instead of `null=True` for `MultiSelectField` if the field is optional.","message":"As a `CharField` subclass, `MultiSelectField` stores values as comma-separated strings. Avoid setting `null=True` on `CharField`s in Django, as it's generally recommended to use `blank=True` and `default=''` for string-based fields.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}