{"id":20127689,"url":"https://github.com/imangazalievm/material-prefs","last_synced_at":"2025-07-22T23:36:22.283Z","repository":{"id":57725169,"uuid":"293368380","full_name":"ImangazalievM/material-prefs","owner":"ImangazalievM","description":"⚙ A beautiful and extensible API for bulding preferences screen","archived":false,"fork":false,"pushed_at":"2021-06-26T21:13:25.000Z","size":2629,"stargazers_count":60,"open_issues_count":2,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-10T02:25:49.227Z","etag":null,"topics":["android","kotlin","material-design","material-preferences","preferences"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ImangazalievM.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-06T21:59:33.000Z","updated_at":"2025-06-25T05:13:25.000Z","dependencies_parsed_at":"2022-09-11T20:20:31.837Z","dependency_job_id":null,"html_url":"https://github.com/ImangazalievM/material-prefs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ImangazalievM/material-prefs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ImangazalievM%2Fmaterial-prefs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ImangazalievM%2Fmaterial-prefs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ImangazalievM%2Fmaterial-prefs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ImangazalievM%2Fmaterial-prefs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ImangazalievM","download_url":"https://codeload.github.com/ImangazalievM/material-prefs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ImangazalievM%2Fmaterial-prefs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266591116,"owners_count":23953060,"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","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["android","kotlin","material-design","material-preferences","preferences"],"created_at":"2024-11-13T20:23:18.988Z","updated_at":"2025-07-22T23:36:22.258Z","avatar_url":"https://github.com/ImangazalievM.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Image](/images/logo.png)\n\n# Material Preferences\n\n![Image](/images/screenshots.png)\n\n## 💻 Installation\n[![Download](https://img.shields.io/maven-central/v/com.imangazaliev.material-prefs/core?label=material-prefs\u0026style=flat)](https://repo1.maven.org/maven2/com/imangazaliev/material-prefs/core)\n[![Licence](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat)](https://opensource.org/licenses/Apache-2.0)\n\nAdd this in app's ```build.gradle``` file:\n```groovy\nimplementation 'com.imangazaliev.material-prefs:core:\u003cversion\u003e'\nimplementation 'com.imangazaliev.material-prefs:dialogs:\u003cversion\u003e'\nimplementation 'com.imangazaliev.material-prefs:date-time:\u003cversion\u003e'\nimplementation 'com.imangazaliev.material-prefs:color-picker:\u003cversion\u003e'\n```\n\n⚠ **Attention!** The package name has been changed from `com.github.imangazalievm.material-prefs:xxx` due to the transfer of the library to Maven Central.\n\n## ⭐ Features\n\n* Convenient and extensible DSL\n* Flexible appearance settings\n* Unified view on Lollipop and Pre-Lollipop\n* Ability to use custom storage\n* Default prefs values\n* Light and dark themes\n\n## 🔥 Usage\n\nTo start using the library you need to do 3 simple steps:\n1. Add `MaterialPreferencesView` in your layout\n2. Provide preferences storage:\u003cbr\u003e\n    3.1 Default storage - `DefaultPreferencesStorage`\u003cbr\u003e\n    3.1 Any custom storage which implements the `PreferencesStorage` interface\n3. Build prefs screen via MaterialPrefs DSL\n\nIf you want to use `DefaultPreferencesStorage` you have to provide initial values through `DefaultValuesContainer`.\n\n**Step 1**\nPlace the `MaterialPreferencesView` in your layout:\n```xml\n\u003ccom.imangazaliev.materialprefs.views.MaterialPreferencesView\n        android:id=\"@+id/prefsView\"\n        android:layout_width=\"match_parent\"\n        android:layout_height=\"match_parent\" /\u003e\n```\n\n**Step 2**\nCreate prefs storage and provide initial values:\n```kotlin\nval defValues = defaultPrefValues {\n    \"my_string\" to \"Jhon Doe\"\n    \"my_int\" to 99\n    \"my_long\" to 5L\n    \"my_float\" to 2.5f\n    \"my_boolean\" to true\n}\n\nval storage = defaultPrefsStorage(\"my_prefs\", defValues)\n```\n\n**Step 3**\nAdd pref items via MaterialPrefs DSL:\n```kotlin\nprefs(prefsView, storage) {\n    category(\"My category\") {\n         preference {\n            title(\"My pref item\")\n            icon(R.drawable.my_icon)\n            onClick {\n                //my action\n            }\n        }\n    }\n}   \n```\n\n## 📄 Documentation\n\nThe library includes 4 modules:\n* **core** - contains main code: simple prefs, checkbox, switch\n* **dialogs** - dialogs prefs: single and multiple choice\n* **date-time** - date and time pickers\n* **color-picker** - color picker\n\nThree last modules based on [Material Dialogs](https://github.com/afollestad/material-dialogs) library.\n\n### Core\n\n**Simple preference:**\n```kotlin\npreference {\n    title(\"Title\")\n    summary(\"My description\")\n    icon(R.drawable.ic_my_icon)\n    showArrow(true)\n    onClick {\n        //my action\n    }\n}\n```\n\n**Switch:**\n```kotlin\nswitch(\"my_key\") {\n    title(\"Title\")\n    summary(\"My description\")\n    onChecked { isChecked -\u003e\n        //my action\n    }\n}\n```\n\n**Checkbox:**\n```kotlin\ncheckbox(\"my_key\") {\n    title(\"Title\")\n    summary(\"My description\")\n    onChecked { isChecked -\u003e\n        //my action\n    }\n}\n```\n\n**Label preference:**\n```kotlin\nlabelPreference(\"my_key\", String::class) {\n    title(\"Title\")\n    onClick {\n        //my action\n    }\n}\n```\n\n### Dialogs\n\n**Single Choice:**\n```kotlin\nlistSingleChoice(\"my_key\", String::class) {\n    title(\"Title\")\n    icon(R.drawable.ic_my_icon)\n    showRadioButtons(true)\n    items(\n        listOf(\n            ListItem(\"ar\", \"Arabic\"),\n            ListItem(\"en\", \"English\"),\n            ListItem(\"ru\", \"Russian\")\n        )\n    )\n}\n```\n\n**Multi Choice:**\n```kotlin\nlistMultiChoice(\"my_key\", String::class) {\n    title(\"Title\")\n    allowEmptySelection(false)\n    //required\n    listValuesSerializer { it.joinToString() }\n    //required\n    listValuesDeserializer {\n        if (it.isNotEmpty()) {\n            it.split(\",\")\n                .map { number -\u003e number.trim().toInt() }\n        } else emptyList()\n    }             \n    items(\n        listOf(\n            ListItem(\"one\", \"Item 1\"),\n            ListItem(\"two\", \"Item 2\"),\n            ListItem(\"three\", \"Item 3\")\n        )\n    )\n}\n```\n\n**Text Input:**\n```kotlin\ntextInput(\"my_key\") {\n    title(\"Title\")\n    icon(R.drawable.ic_username)\n    onNewInput { \n        //my action       \n    }\n}\n```\n\n### DateTime\n\n**Date picker:**\n```kotlin\ndatePicker(\"my_key\") {\n    title(\"Title\")\n    val formatter = SimpleDateFormat(\"dd.MM.yyyy \", Locale.US)\n    valuePresenter { formatter.format(it) }\n    onValueSelected {\n        //my action\n    }\n}\n```\n\n**Time picker:**\n```kotlin\ntimePicker(\"my_key\") {\n    title(\"Title\")\n    val formatter = SimpleDateFormat(\"hh:mm \", Locale.US)\n    valuePresenter { formatter.format(it) }\n    onValueSelected {\n        //my action\n    }\n}\n```\n\n**Date and picker:**\n```kotlin\ndateTimePicker(\"my_key\") {\n    title(\"Title\")\n    val formatter = SimpleDateFormat(\"hh:mm dd.MM.yyyy \", Locale.US)\n    valuePresenter { formatter.format(it) }\n    onValueSelected {\n        //my action\n    }\n}\n```\n\n\n### ColorPicker\n\n```kotlin\ncolorPicker(\"my_key\") {\n    title(\"Title\")\n    val colors = intArrayOf(Color.RED, Color.GREEN, Color.BLUE)\n    colors(colors)\n    onColorSelected {\n        //my action\n    }\n}\n```\n\n### Custom preference item\n\nTo create custom preference item you have to do 3 steps:\n\n**Step 1:**\nCreate preference view class inherited from `PreferenceView` or `BasePreferenceView`. \n\nIf your view inherited from `BasePreferenceView` you have to implement `createValueView` method:\n\n```kotlin\nclass MyPreferenceView(\n    context: Context,\n    attrs: AttributeSet? = null,\n    themeResId: Int = 0\n) : BasePreferenceView(context, attrs, themeResId) {\n\n    override fun createValueView(parent: ViewGroup): View {\n        return parent.inflate(R.layout.my_pref_view)\n    }\n\n}\n```\n\n**Step 2:**\nCreate preference class inherited from `Preference` or `BasePreference` and implement 3 methods:\n```kotlin\nabstract class MyPreference(\n    key: String,\n    container: PrefsContainer,\n    private val appearanceManager: PreferencesAppearance\n) : BasePreference\u003cMyPreference, MyPreferenceView, String\u003e(\n    container = container,\n    key = key,\n    appearanceManager = appearanceManager\n) {\n\n    override fun createView(): V {\n    }\n\n    override fun loadValue(view: V) {\n    }\n \n    override fun initView(view: V) {\n    }\n\n}\n```\n\nThird generic parameter of `BasePreference` is a type of data, that will be save in the preferences, so it must be one of the following types:\n* String\n* Int\n* Long\n* Float\n* Boolean\n\n**Step 3:**\nCreate extension method for `MaterialSettings`:\n```kotlin\nfun myPreference(builder: PreferenceBuilder\u003cMyPreference\u003e) {\n    MyPreference(container, appearanceManager)\n        .apply(builder)\n        .also { addPreference(it) }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimangazalievm%2Fmaterial-prefs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimangazalievm%2Fmaterial-prefs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimangazalievm%2Fmaterial-prefs/lists"}