# App Settings {% tabs %} {% tab title="JavaScript" %} A Homey App can save settings that are persistent across reboots. These settings can be accessed from anywhere in your app through [`ManagerSettings`](https://apps-sdk-v3.developer.homey.app/ManagerSettings.html). You can also create a page where users can update the App Settings. {% hint style="info" %} Custom app setting views are not allowed on Homey Cloud. Any information your app might need to function should be asked for when pairing a device. Read the [Custom Pairing Views](/advanced/custom-views/custom-pairing-views.md) documentation for more information. {% endhint %} {% code title="/app.js" %} ```javascript const Homey = require('homey'); class App extends Homey.App { async onInit() { const username = this.homey.settings.get('username'); // ... } } module.exports = App; ``` {% endcode %} {% endtab %} {% tab title="TypeScript" %} A Homey App can save settings that are persistent across reboots. These settings can be accessed from anywhere in your app through [`ManagerSettings`](https://apps-sdk-v3.developer.homey.app/ManagerSettings.html). You can also create a page where users can update the App Settings. {% hint style="info" %} Custom app setting views are not allowed on Homey Cloud. Any information your app might need to function should be asked for when pairing a device. Read the [Custom Pairing Views](/advanced/custom-views/custom-pairing-views.md) documentation for more information. {% endhint %} {% code title="/app.mts" %} ```mts import Homey from "homey"; export default class App extends Homey.App { async onInit(): Promise { const username = this.homey.settings.get("username"); // ... } } ``` {% endcode %} {% endtab %} {% tab title="Python" %} A Homey App can save settings that are persistent across reboots. These settings can be accessed from anywhere in your app through [`ManagerSettings`](https://python-apps-sdk-v3.developer.homey.app/manager/settings.html#homey.manager.settings.ManagerSettings). You can also create a page where users can update the App Settings. {% hint style="info" %} Custom app setting views are not allowed on Homey Cloud. Any information your app might need to function should be asked for when pairing a device. Read the [Custom Pairing Views](/advanced/custom-views/custom-pairing-views.md) documentation for more information. {% endhint %} {% code title="/app.py" %} ```python from homey import app class App(app.App): async def on_init(self) -> None: username = self.homey.settings.get("username") ... homey_export = App ``` {% endcode %} {% endtab %} {% endtabs %} ## Creating an App Settings page To create a settings view, create a folder named `/settings/` in your app's root, and create a new file named `index.html` in it. Include the following script in your ``: {% code title="/settings/index.html" %} ```markup ``` {% endcode %} Next, add a function called `onHomeyReady`: {% code title="/settings/index.html" %} ```markup ``` {% endcode %} The first argument of `onHomeyReady` will be a `Homey` instance, which can be used to communicate with Homey. Finally, call `Homey.ready()` to show the settings view. ### Example Below is a simple example to save a username & password. Learn more about[ HTML usage and CSS styling.](/advanced/custom-views/html-and-css-styling.md)

<!DOCTYPE html>
<html>
  <head>
    <!-- The '/homey.js' script must be included in your settings view to work -->
    <script
      type="text/javascript"
      src="/homey.js"
      data-origin="settings"
    ></script>
  </head>
  <body>
    <header class="homey-header">
      <h1 class="homey-title" data-i18n="settings.title">
        <!-- This will be filled with the translated string with key 'settings.title'. -->
      </h1>
      <p class="homey-subtitle" data-i18n="settings.subtitle">
        <!-- This field will also be translated -->
      </p>
    </header>

    <fieldset class="homey-form-fieldset">
      <legend class="homey-form-legend">My Settings</legend>

      <div class="homey-form-group">
        <label class="homey-form-label" for="username">Username</label>
        <input class="homey-form-input" id="username" type="text" value="" />
      </div>
      <div class="homey-form-group">
        <label class="homey-form-label" for="password">Password</label>
        <input class="homey-form-input" id="password" type="password" value="" />
      </div>
    </fieldset>

    <button id="save" class="homey-button-primary-full">Save changes</button>

    <script type="text/javascript">
      // a method named 'onHomeyReady' must be present in your code
      function onHomeyReady(Homey) {
        // Tell Homey we're ready to be displayed
        Homey.ready();

        var usernameElement = document.getElementById("username");
        var passwordElement = document.getElementById("password");
        var saveElement = document.getElementById("save");

        Homey.get("username", function (err, username) {
          if (err) return Homey.alert(err);
          usernameElement.value = username;
        });

        Homey.get("password", function (err, password) {
          if (err) return Homey.alert(err);
          passwordElement.value = password;
        });

        saveElement.addEventListener("click", function (e) {
          Homey.set("username", usernameElement.value, function (err) {
            if (err) return Homey.alert(err);
          });
          Homey.set("password", passwordElement.value, function (err) {
            if (err) return Homey.alert(err);
          });
        });
      }
    </script>
  </body>
</html>

{% code title="/locales/en.json" %} ```javascript { "settings": { "title": "My Settings Page", "subtitle": "Please log in" } } ``` {% endcode %} ## Settings View API ### `Homey.ready()` The settings view will be hidden until this method has been called. Use the extra time to make required API calls to prevent flickering on screen. ### `Homey.get( [String name,] Function callback )` Gets a single setting's value when `name` is provided, or an object with all settings when `name` is omitted. ### `Homey.set( String name, Mixed value, Function callback )` Sets a single setting's value. The value must be JSON-serializable. ### `Homey.unset( String name, Function callback )` Unsets a single setting's value. ### `Homey.on( String event, Function callback )` Register an event listener for your app's realtime events. System events when modifying settings are: `settings.set`, `settings.unset`. ### `Homey.api( String method, String path, Mixed body, Function callback )` Make a call to your App's Web API. The first argument `method` can be either `GET`, `POST`, `PUT` or `DELETE`. The second argument `path` is relative to your app's API endpoint. The third argument `body` is optional, and `null` can be provided to ignore it. For example: {% code title="/settings/index.html" %} ```markup ``` {% endcode %} ### `Homey.alert( String message, Function callback )` Show an alert dialog. ### `Homey.confirm( String message, Function callback )` Show a confirm dialog. The callback's 2nd argument will be `true` when the user pressed `OK`. ### `Homey.popup( String url[, Object opts] )` Show a popup (new window). The object `opts` can optionally have a `width` and `height` property of type `number`. The default width and height is `400`. ### `Homey.openURL( String url )` Show a new window. ### `Homey.__( String key [, Object tokens] )` Translate a string programmatically. The first argument `key` is the name in your `/locales/__language__.json`. Use dots to get a sub-property, e.g. `settings.title`. The optional second argument `tokens` is an object with replacers. Read more about translations in the [internationalization guide](/the-basics/app/internationalization.md). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://apps.developer.homey.app/advanced/custom-views/app-settings.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.