Skip to content

Quick Settings Tiles

Jump to bottom
sameerasw edited this page Aug 19, 2026 · 2 revisions

⚡ Quick Settings Tiles

Essentials provides 25+ Quick Settings tiles that you can add to your notification shade for instant access to system settings and feature toggles. All tiles are managed in-app from the Quick Settings Tiles settings screen.

Adding Tiles to Your Device

  1. Open Essentials → Quick Settings Tiles section
  2. Each tile has an "Add" button — tap it to add directly to your QS panel
  3. Or manually drag from the QS tile editor (pull down notification shade → tap pencil icon → find Essentials tiles)

All Available Tiles

Display & Screen

Tile Service Class Description Permission
UI Blur UiBlurTileService Toggle system UI blur/frosted glass effect WRITE_SECURE_SETTINGS
Always on Display (AOD) AlwaysOnDisplayTileService Toggle AOD on/off WRITE_SECURE_SETTINGS
Tap to Wake TapToWakeTileService Toggle tap-to-wake on/off WRITE_SETTINGS
Refresh Rate RefreshRateTileService Cycle through refresh rate modes (Auto/Fixed/Peak) WRITE_SECURE_SETTINGS (Pixel only)
Scale Animations ScaleAnimationsTileService Toggle UI animations on/off WRITE_SETTINGS
Adaptive Brightness AdaptiveBrightnessTileService Toggle adaptive brightness WRITE_SETTINGS
Dynamic Night Light DynamicNightLightTileService Toggle app-based night light —
Pocket Mode PocketModeTileService Toggle pocket mode ACCESSIBILITY

Audio & Sound

Tile Service Class Description Permission
Sound Mode SoundModeTileService Cycle Normal / Vibrate / Silent ACCESS_NOTIFICATION_POLICY
Mono Audio MonoAudioTileService Toggle mono audio output SHIZUKU/ROOT

Notifications & Alerts

Tile Service Class Description Permission
Notification Lighting NotificationLightingTileService Toggle edge lighting —
Flashlight Pulse FlashlightPulseTileService Toggle flashlight notification pulse —
Sensitive Content PrivateNotificationsTileService Toggle notification content hiding on lock screen —
Bubbles BubblesTileService Toggle chat bubbles WRITE_SECURE_SETTINGS

Power & Battery

Tile Service Class Description Permission
Caffeinate CaffeinateTileService Toggle screen-on wake lock with timer options POST_NOTIFICATIONS
Stay Awake StayAwakeTileService Keep screen on while charging WRITE_SETTINGS
Charge Optimization ChargeQuickTileService Toggle charging optimization (limit to 80%) ROOT (Pixel only)
Maps Power Saving MapsPowerSavingTileService Toggle Maps power saving mode SHIZUKU/ROOT

Security

Tile Service Class Description Permission
Screen Locked Security ScreenLockedSecurityTileService Toggle QS restriction when locked SHIZUKU/ROOT
App Lock AppLockTileService Toggle app lock on/off ACCESSIBILITY
Lockdown LockdownTileService Instantly enter lockdown mode DEVICE_ADMIN

Network & Connectivity

Tile Service Class Description Permission
Private DNS PrivateDnsTileService Cycle through DNS presets (Off / Auto / Custom) WRITE_SECURE_SETTINGS
NFC NfcTileService Toggle NFC on/off —
USB Debugging UsbDebuggingTileService Toggle USB ADB debugging WRITE_SECURE_SETTINGS

Developer & System

Tile Service Class Description Permission
Developer Options DeveloperOptionsTileService Toggle developer options WRITE_SECURE_SETTINGS
Flashlight FlashlightTileService Torch with brightness control —
App Freezing AppFreezingTileService Freeze all selected apps SHIZUKU/ROOT
Color Picker ColorPickerTileService Open system color picker (Android 17+) —
Restart SystemUI RestartSystemUiTileService Restart SystemUI process SHIZUKU/ROOT

Private DNS Tile — Detail

The Private DNS tile cycles through up to 4 modes with each tap:

  1. Off — No Private DNS
  2. Automatic — DNS over TLS with opportunistic encryption
  3. Custom 1 — Your first preset hostname (e.g., dns.cloudflare.com)
  4. Custom 2 — Your second preset hostname (e.g., dns.adguard.com)

Configure your custom DNS hostnames from the Networks settings screen.

Tile Architecture & Lifecycle

All Essentials tiles extend BaseTileService:

BaseTileService (TileService)
├── onTileClick()         — Background execution logic for toggle/action
├── getTileState()        — Returns ACTIVE / INACTIVE / UNAVAILABLE
├── getTileLabel()        — Returns tile label string
├── getTileSubtitle()     — Returns subtitle string (e.g., On/Off, timer remaining)
├── getTileIcon()         — Returns dynamic icon resource
├── hasFeaturePermission()— Checks required permissions
└── isDeviceSupported()   — Verifies hardware / OEM support

BaseTileService provides automatic haptic feedback, asynchronous coroutine dispatching on click, fallback to Shizuku/root shell for setting adjustments (getSecureInt, putSecureInt, getGlobalInt, putGlobalInt), and processing state animations.

Contributor Guide: How to Add a New QS Tile

Adding a Quick Settings tile to Essentials involves 6 core steps across the codebase:

1. Create the Service Class (services/tiles/)

Create a new Kotlin class in app/src/main/java/com/sameerasw/essentials/services/tiles/YourTileService.kt extending BaseTileService:

package com.sameerasw.essentials.services.tiles

import android.Manifest
import android.content.pm.PackageManager
import android.graphics.drawable.Icon
import android.service.quicksettings.Tile
import com.sameerasw.essentials.R

class YourTileService : BaseTileService() {

    override fun getTileLabel(): String = getString(R.string.tile_your_feature)

    override fun getTileSubtitle(): String {
        return if (isFeatureEnabled()) getString(R.string.on) else getString(R.string.off)
    }

    override fun hasFeaturePermission(): Boolean {
        return checkCallingOrSelfPermission(Manifest.permission.WRITE_SECURE_SETTINGS) == PackageManager.PERMISSION_GRANTED
    }

    override fun getTileIcon(): Icon? {
        val iconRes = if (isFeatureEnabled()) R.drawable.rounded_feature_on_24 else R.drawable.rounded_feature_off_24
        return Icon.createWithResource(this, iconRes)
    }

    override fun getTileState(): Int {
        return if (isFeatureEnabled()) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    }

    override fun onTileClick() {
        val newState = if (isFeatureEnabled()) 0 else 1
        putSecureInt("your_secure_setting_key", newState)
    }

    private fun isFeatureEnabled(): Boolean {
        return getSecureInt("your_secure_setting_key", 0) == 1
    }
}

2. Declare in AndroidManifest.xml

Add the service declaration under <application>:

<service
    android:name=".services.tiles.YourTileService"
    android:exported="true"
    android:icon="@drawable/rounded_your_feature_24"
    android:label="@string/tile_your_feature"
    android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
    <intent-filter>
        <action android:name="android.service.quicksettings.action.QS_TILE" />
    </intent-filter>
    <meta-data
        android:name="android.service.quicksettings.TILE_CATEGORY"
        android:value="android.service.quicksettings.CATEGORY_UTILITIES" />
</service>

3. Add String Resources (res/values/strings.xml)

Define localized strings for title and about description:

<string name="tile_your_feature">Your Feature</string>
<string name="about_desc_your_feature">Description explaining what your feature tile does.</string>

4. Register in QsTileRegistry.kt (Discovery & Favorite Widget)

Add the entry to QsTileRegistry.ALL_TILES:

QsTileEntry(
    titleRes = R.string.tile_your_feature,
    iconRes = R.drawable.rounded_your_feature_24,
    serviceClass = YourTileService::class.java
),

Note: QsTileRegistry powers the Favorite QS Tiles Glance Widget (QsTilesWidget) and lock screen shortcuts. Standard BaseTileService implementations have their active state, icon, and subtitles queried dynamically via reflection.

5. Support Headless Widget Clicks (QsTileActionRouter.kt)

When tapped from the Favorite QS Tiles Glance Widget, actions route through QsTileActionRouter. Standard BaseTileService classes are executed headlessly by default. If your tile triggers an external service, controller, or custom flow, add an explicit branch in QsTileActionRouter.kt.

6. Register in Quick Settings Tiles UI (QuickSettingsTilesSettingsUI.kt)

All tiles MUST be listed in the in-app tile manager screen so users can view permissions and tap "Add" to install them via StatusBarManager.requestAddTileService():

QSTileInfo(
    titleRes = R.string.tile_your_feature,
    iconRes = R.drawable.rounded_your_feature_24,
    serviceClass = YourTileService::class.java,
    permissionKeys = listOf("WRITE_SECURE_SETTINGS"), // "SHIZUKU", "ROOT", "ACCESSIBILITY", or emptyList()
    aboutDescription = R.string.about_desc_your_feature,
    categoryRes = R.string.cat_utils // e.g., R.string.cat_visuals, R.string.cat_privacy
)

In-App Tile Manager

The Quick Settings Tiles settings screen in Essentials (QuickSettingsTilesSettingsUI.kt) provides:

  • All available tiles categorized with their icons, descriptions, and about bottom sheets
  • Real-time active state queries
  • Quick "Add" button using StatusBarManager.requestAddTileService() (Android 13+)
  • Interactive permission cards & guidance sheets for required permissions

Clone this wiki locally