{"id":19718953,"url":"https://github.com/vholik/medusa-custom-attributes","last_synced_at":"2025-05-07T06:03:34.542Z","repository":{"id":202719085,"uuid":"707394504","full_name":"vholik/medusa-custom-attributes","owner":"vholik","description":"Plugin that extends MedusaJs with custom attributes API","archived":false,"fork":false,"pushed_at":"2024-06-04T13:27:37.000Z","size":153,"stargazers_count":100,"open_issues_count":14,"forks_count":20,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-07T06:03:00.355Z","etag":null,"topics":["admin-ui","e-commerce","medusajs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vholik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-19T20:03:52.000Z","updated_at":"2025-05-04T15:51:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"27bdad6d-7576-4584-9c28-899e0fa0158c","html_url":"https://github.com/vholik/medusa-custom-attributes","commit_stats":{"total_commits":91,"total_committers":1,"mean_commits":91.0,"dds":0.0,"last_synced_commit":"d2f73c2473c0e71ba8a82c9e07d54d84cadeac74"},"previous_names":["vholik/medusa-custom-attributes"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vholik%2Fmedusa-custom-attributes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vholik%2Fmedusa-custom-attributes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vholik%2Fmedusa-custom-attributes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vholik%2Fmedusa-custom-attributes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vholik","download_url":"https://codeload.github.com/vholik/medusa-custom-attributes/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252823922,"owners_count":21809713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["admin-ui","e-commerce","medusajs"],"created_at":"2024-11-11T23:02:46.188Z","updated_at":"2025-05-07T06:03:34.509Z","avatar_url":"https://github.com/vholik.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Medusa Custom Attributes Plugin\n\n# Tutorials\n\nHere is some articles how to add custom attributes and handle them on storefont:\n\n1. [How to add attributes in admin panel](https://medium.com/rigby-software-house/adding-custom-attributes-in-medusa-js-ba1af9f312bb)\n2. [How to handle attributes on storefront](https://medium.com/rigby-software-house/introducing-custom-attributes-in-medusa-js-part-2-ui-8c1f111f8845)\n\nhttps://github.com/vholik/medusa-custom-attributes/assets/109461604/75d826ea-9725-4a8d-a35d-c264740abc44\n\nThe Medusa Custom Attributes Plugin is designed to enhance your e-commerce platform with custom attributes, providing compatibility with versions \u003e= 1.20.0 of `@medusajs/medusa`.\n\n## Features\n\n1. **Diverse Attribute Types**: The plugin supports multi, single, range and boolean attributes, enabling a wide range of attribute customizations. 🤯\n2. **Effortless Ranking**: Easily rank attribute values via a drag-and-drop interface in the admin panel. 🤌🏻\n3. **Efficient Product Filtering**: Filter your products with ease by using these custom attributes. 💪\n4. **Category-Based Attributes**: You can get attributes specific to particular categories, ensuring attribute relevance. 👀\n\n## Getting Started\n\n### Installation\n\nTo get started, install the Medusa Custom Attributes Plugin with either npm or yarn:\n\n```bash\nnpm install medusa-custom-attributes\n```\n\nor\n\n```bash\nyarn add medusa-custom-attributes\n```\n\n(Optional) Next toggle categories feature flag to your .env:\n\n```dotenv\nMEDUSA_FF_PRODUCT_CATEGORIES=true\n```\n\n### Configuration\n\nNext, add the plugin to your medusa-config.js file as follows:\n\n```js\nconst plugins = [\n  // ...\n  {\n    resolve: `medusa-custom-attributes`,\n    options: {\n      enableUI: true,\n      projectConfig: {\n        store_cors: STORE_CORS,\n        admin_cors: ADMIN_CORS,\n      },\n    },\n  },\n];\n```\n\nAnd run migrations:\n\n```bash\nnpx medusa migrations run\n```\n\nNow you're all set and ready to launch! 🚀\n\n### Why Use the Medusa Custom Attributes Plugin?\n\nThe Medusa Custom Attributes Plugin empowers you to define custom attributes within categories and apply them to your products. With this plugin, you can filter your products based on these custom attributes, offering a more tailored shopping experience for your customers.\n\n### Using on storefront\n\nTo get custom attributes make a `/store/attributes` request. If you want to get attributes that is related to certain categories use `/store/attributes?categories[]=CATEGORY_HANDLE` param\n\nAfter adding custom attributes to product, you can see field `attribute_values` in product responses. Also, you can filter them using query parameters in the URL. For example:\n\n```bash\n/store/products?attributes[]=ATTRIBUTE_VAL_ID\n```\n\nHere's an example URL:\n\n```bash\n/store/products?attributes[]=attr_val_01HDZX4VRNP8PNB3FYJXHAGMWG\u0026attributes[]=attr_val_BQDHQ342NB3FYJXHA4353\n```\n\nthis corresponds to the following Axios request:\n\n```jsx\naxios.get(\"http://localhost:9000/store/products\", {\n  params: {\n    attributes: [\n      \"attr_val_01HDZX4VRNP8PNB3FYJXHAGMWG\",\n      \"attr_val_BQDHQ342NB3FYJXHA4353\",\n    ],\n  },\n});\n```\n\n### Using range attributes\n\nAs range attribute is a different table you should use different query to filter products by range attributes:\n\n```bash\n/store/products?int_attributes[RANGE_ATTRIBUTE_ID][]=0\u0026int_attributes[RANGE_ATTRIBUTE_ID][]=61 // Range from 0 to 61 (included)\n```\n\nHere is an URL example with using range attributes:\n\n```bash\n/store/products?int_attributes[attr_01HEJ929XKX88616FYER0SM165][]=0\u0026int_attributes[attr_01HEJ929XKX88616FYER0SM165][]=61\n```\n\nthis corresponds to the following Axios request:\n\n```jsx\naxios.get(\"http://localhost:9000/store/products\", {\n  params: {\n    int_attributes: {\n      attr_01HEJ929XKX88616FYER0SM165: [0, 61],\n    },\n  },\n});\n```\n\nIn response we get:\n\n```json\n{\n  // ...product fields\n  \"custom_attributes\": [\n    {\n      \"id\": \"attr_01HEJ929XKX88616FYER0SM165\",\n      \"created_at\": \"2023-11-06T12:17:38.228Z\",\n      \"updated_at\": \"2023-11-06T12:17:38.228Z\",\n      \"name\": \"Custom attribute\",\n      \"description\": \"\",\n      \"type\": \"range\",\n      \"handle\": \"range-test\",\n      \"filterable\": true,\n      \"metadata\": null,\n      \"value\": {\n        \"id\": \"int_attr_val_01HEN6GZ3C1X7Q11Y7XXZJHNTY\",\n        \"created_at\": \"2023-11-07T14:30:55.792Z\",\n        \"updated_at\": \"2023-11-07T14:30:55.792Z\",\n        \"value\": 61\n      }\n    },\n    {\n      \"id\": \"attr_01HEN6HFFF0KEMNT1Y70GYM66F\",\n      \"created_at\": \"2023-11-07T15:31:13.008Z\",\n      \"updated_at\": \"2023-11-07T15:31:13.008Z\",\n      \"name\": \"Custom attribute 2\",\n      \"description\": \"\",\n      \"type\": \"range\",\n      \"handle\": \"custom-attribute-2\",\n      \"filterable\": true,\n      \"metadata\": null,\n      \"value\": {\n        \"id\": \"int_attr_val_01HEN738CKGVZ0AWDHTH2SJBR4\",\n        \"created_at\": \"2023-11-07T14:40:55.070Z\",\n        \"updated_at\": \"2023-11-07T14:40:55.070Z\",\n        \"value\": 60\n      }\n    }\n  ]\n}\n```\n\n### API Reference\n\n#### Entity\n\n```tsx\nexport enum AttributeType {\n  MULTI = \"multi\", // Allows you to define several attribute values from the same attribute.\n  SINGLE = \"single\", // Permits only 1 value from the attribute.\n  BOOLEAN = \"boolean\", // Represents a boolean value (e.g., checkbox).\n  RANGE = \"range\", // Integer\n}\n```\n\nAttribute values also have a JSONB metadata field in which you can define any additional values you require. Here's an example:\n\n```json\n// POST: /admin/attributes\n\n{\n  \"categories\": [\"pcat_shirts\"],\n  \"description\": \"Color attribute\",\n  \"handle\": \"color\",\n  \"name\": \"Color\",\n  \"type\": \"multi\",\n  \"values\": [\n    {\n      \"rank\": 0, // Ranking is used to display values in the desired order.\n      \"value\": \"Black\",\n      \"metadata\": {\n        \"color\": \"#000\"\n      }\n    },\n    {\n      \"rank\": 1,\n      \"value\": \"White\",\n      \"metadata\": {\n        \"color\": \"#fff\"\n      }\n    }\n  ],\n  \"metadata\": {\n    \"color_attribute\": true\n  }\n}\n```\n\n### API Routes\n\n1. `/admin/attributes` (GET) - Get a list of attributes. Parameters: \"categories\" (category handles). Example: ?categories[0]=t-shirts.\n\n2. `/store/attributes` (GET) - Get a list of attributes with field `filterable` set to `true`. Parameters: \"categories\" (category handles). Example: ?categories[0]=t-shirts.\n\n3. `/admin/attributes` (POST) - Create a custom attribute.\n\n4. `/admin/attributes/:id` (GET) - Get an attribute by its ID.\n\n5. `/admin/attributes/:id` (POST) - Update an attribute.\n\n6. `/admin/attributes/:id` (DELETE) - Delete an attribute.\n\n### Global Attributes\n\nTo define global attributes that are not tied to specific categories, simply leave the \"categories\" field empty when creating the attribute.\n\n### Changelog\n\n- 2/20/202: Replacing `int_attribute_values` and `attribute_values` with simple `custom_attributes`.\n- 1/16/2023: Updating plugin to the latest version of Medusajs (1.20.0), improve performance on filtering, refactoring code, change attributes filtering\n- 11/8/2023: Adding range attribute, fix attributes filter bug\n- 11/3/2023: Remove is_bool field in attribute_value model, fixing minor bugs\n\n### Other Links\n\nIf you find this plugin useful, please consider giving it a star. Developed by in [Rigby](https://www.linkedin.com/company/rigby-software).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvholik%2Fmedusa-custom-attributes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvholik%2Fmedusa-custom-attributes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvholik%2Fmedusa-custom-attributes/lists"}