Settings

Every plugin can have a settings page, opened with the cog next to it in Settings → Plugins. There are two ways to fill it: declared settings, where Nari draws the editor and stores the value for you, and built entries, where you decide what happens.

Declared settings

nari.setting({ key = "api_key", title = "API key", description = "From your account page", private = true })
nari.setting({ key = "quality", title = "Quality", type = "choice", default = "high",
  options = { "low", "high", { value = "lossless", label = "Lossless (FLAC)" } } })
nari.setting({ key = "previews", title = "Show previews", type = "toggle", default = true,
  changed = function(on) nari.log("previews are now", on) end })

local key = nari.get("api_key")

Key
key, title	Required. nari.get(key) reads the value.
type	text (default), number, toggle or choice.
options	For choice: values, or { value, label } tables.
default	Shown while nothing is stored. nari.get returns nil then.
private	Keeps the value in private storage and shows •••• instead.
description, icon, section	Like in built entries below.
changed	Called with the new value after the user changes it.

Declared settings come first on the page.

Built entries

nari.settings(function()
  return {
    {
      title = "Say hello on start",
      description = "Logs a greeting every time a song starts",
      icon = "icon.svg",
      value = function() return nari.get("greet") and "On" or "Off" end,
      action = function() nari.set("greet", not nari.get("greet")) end,
    },
  }
end)

The builder runs every time the page is drawn, so entries can change. Each entry has:

Key
title, description	Texts.
icon	A path in the plugin folder, a res:// path or a texture. A generic icon by default.
value	A function returning the text on the right, like "On" or "3 active".
action	Called when the entry is picked. Open a Dialog for anything more complex.
reset	Optional, called when the user resets the entry.
section	Optional category for the entry.

Categories

Every Settings page groups its entries under categories. nari.settings_entry(page, builder) adds entries to one of Nari’s pages; they go under a category named after your plugin, unless they set section:

nari.settings_entry("playback", function()
  return {
    { title = "Crossfade", section = "Playback", value = function() return "Off" end, action = function() end },
  }
end)

Use the name of an existing category to join it, or a new name to create one (new ones go after the existing ones). Entries without section on the plugin’s own page go first, with no name above them.

Page	Categories
general	Screens (Window on desktop), Startup, Library, Interface, Developer
library	Source, the provider’s name, Library, History
playback	Playback, MIDI and modules, Quality
appearance	Theme, Layout, Performance
lyrics	Sources, Display
integrations	Discord, Scrobbling