Extension Settings

Define configurable settings for your extension that store owners can customize from the Qumra Admin.

Defining Settings

Settings are defined in the extension configuration. Each setting field has a type, label, and optional default value.

import type { SettingsDefinition } from "@qumra/riwaq";

const settings: SettingsDefinition = {
  fields: [
    {
      type: "text",
      key: "title",
      label: "Block Title",
      default: "Product Insights",
    },
    {
      type: "number",
      key: "maxItems",
      label: "Max Items to Show",
      default: 5,
      min: 1,
      max: 20,
    },
    {
      type: "boolean",
      key: "showBadge",
      label: "Show Status Badge",
      default: true,
    },
    {
      type: "select",
      key: "layout",
      label: "Layout Style",
      default: "grid",
      options: [
        { label: "Grid", value: "grid" },
        { label: "List", value: "list" },
        { label: "Compact", value: "compact" },
      ],
    },
    {
      type: "color",
      key: "accentColor",
      label: "Accent Color",
      default: "#3B82F6",
    },
    {
      type: "range",
      key: "opacity",
      label: "Opacity",
      default: 100,
      min: 0,
      max: 100,
      step: 5,
    },
  ],
};

Setting Field Types

Text

A single-line text input.

{
  type: "text",
  key: "title",
  label: "Title",
  default: "My Extension",
}

Property	Type	Required	Description
type	"text"	Yes	Field type.
key	string	Yes	Unique setting key.
label	string	Yes	Display label.
default	string	No	Default value.

Number

A numeric input with optional min/max bounds.

{
  type: "number",
  key: "limit",
  label: "Item Limit",
  default: 10,
  min: 1,
  max: 100,
}

Property	Type	Required	Description
type	"number"	Yes	Field type.
key	string	Yes	Unique setting key.
label	string	Yes	Display label.
default	number	No	Default value.
min	number	No	Minimum value.
max	number	No	Maximum value.

Boolean

A toggle switch.

{
  type: "boolean",
  key: "enabled",
  label: "Enable Feature",
  default: false,
}

Select

A dropdown with predefined options.

{
  type: "select",
  key: "theme",
  label: "Theme",
  default: "light",
  options: [
    { label: "Light", value: "light" },
    { label: "Dark", value: "dark" },
  ],
}

Property	Type	Required	Description
options	{ label: string; value: string }[]	Yes	Available choices.

Color

A color picker.

{
  type: "color",
  key: "bgColor",
  label: "Background Color",
  default: "#FFFFFF",
}

Range

A slider with min, max, and step.

{
  type: "range",
  key: "fontSize",
  label: "Font Size",
  default: 16,
  min: 10,
  max: 32,
  step: 2,
}

Property	Type	Required	Description
min	number	Yes	Minimum value.
max	number	Yes	Maximum value.
step	number	No	Step increment. Default: 1.

Accessing Settings

Use the useSettings() hook to read settings values in your extension:

import { useSettings } from "@qumra/riwaq";

function MyExtension() {
  const settings = useSettings();

  return (
    <div style={{ color: settings.accentColor as string }}>
      <h3>{settings.title as string}</h3>
      {settings.showBadge && <span>Active</span>}
    </div>
  );
}

Metafields

Extensions can also define metafields for storing custom data:

import type { MetafieldDefinition } from "@qumra/riwaq";

const metafields: MetafieldDefinition[] = [
  {
    namespace: "my-app",
    key: "product-score",
    type: "number_integer",
  },
  {
    namespace: "my-app",
    key: "notes",
    type: "multi_line_text",
  },
];

Metafield Types

Type	Description
single_line_text	Single line text string.
multi_line_text	Multi-line text.
number_integer	Integer number.
number_decimal	Decimal number.
boolean	True/false value.
json	JSON data.
url	URL string.