TopbarPlus

Methods tagged with toggleable in the API allow you to specify an iconState to apply a value only during specific interaction states. If no state is provided, the value applies to all states.

Supported states (case-insensitive):

• "Deselected": Applies when the icon is not pressed.
• "Selected": Applies when the icon is pressed.
• "Viewing": Applies when a cursor hovers over, a controller highlights, or a mobile user long-presses the icon (before release).

-- Example: Changing labels based on state
Icon.new()
    :setImage(4882429582)
    :setLabel("Closed", "Deselected")
    :setLabel("Open", "Selected")
    :setLabel("Viewing", "Viewing")

TopbarPlus includes built-in support for gamepads and consoles. Users can navigate the topbar via a virtual cursor or by pressing DPadUp to highlight the last-selected icon (or the leftmost icon if none are selected).

To change the default trigger keycode from DPadUp, use:

Icon.highlightKey = Enum.KeyCode.NEW_KEYCODE

TopbarPlus is designed to support multiple Icon packages within a single Roblox experience without conflicts, provided all packages are version v3.0.0 or above.

When a new TopbarPlus package is required, it automatically checks if a TopbarPlus instance has already been initialized in the experience. If an instance is found, the new package cancels its own loading process and refers to the existing, already-initialized package. This mechanism ensures that third-party libraries or plugins using TopbarPlus do not interfere with your own implementation.

To prevent icons from overlapping on smaller screens or mobile devices in portrait mode, TopbarPlus uses an overflow system.

• Left-set or right-set icons will trigger an overflow if they exceed the boundary of the closest opposite-aligned icon or the viewport.
• If a center-aligned icon exceeds the bounds of another icon, its alignment will automatically switch to match the alignment of the icon it exceeded.

To use TopbarPlus in a Rojo-based workflow:

1. Fork the TopbarPlus repository.
2. Clone your fork into your local project repository.
3. Modify the serve.project.json file to set your desired location (the default is Workspace).
4. Run rojo serve via your terminal or VS Code plugin and connect using the Rojo Studio plugin.

To use TopbarPlus, require the Icon module from ReplicatedStorage within a LocalScript (typically placed in StarterPlayerScripts). Calling Icon.new() constructs an empty 32x32 icon on the topbar.

By default, icons are ordered based on their construction sequence using the formula 1+(totalCreatedIcons*0.01). Icons created earlier have a lower order and appear further to the left.

-- Within a LocalScript in StarterPlayerScripts
local Icon = require(game:GetService("ReplicatedStorage").Icon)
local icon = Icon.new()

If you prefer not to use the Roblox Model system, you can download the model file directly:

1. Visit the latest release on GitHub.
2. Under the Assets section, download TopbarPlus.rbxm.
3. In Roblox Studio, go to MODEL -> Model and insert the downloaded file anywhere within ReplicatedStorage.

You can customize an icon's appearance by using setImage(imageId) and setLabel("Label"). These methods are chainable, allowing you to configure the icon in a single statement.

To perform logic on an icon during the construction chain, use the :call(function(icon) ... end) method. This passes the icon instance as the first argument to your function.

-- Using method chaining
Icon.new()
    :setImage(imageId)
    :setLabel("Label")

-- Using :call to act on the icon during construction
Icon.new()
    :setName("TestIcon")
    :call(function(icon)
        print(icon.name) -- Prints 'TestIcon'
    end)

TopbarPlus is available as a Wally package. You can install it using the following package identifier:

1foreverhd/topbarplus

Find the package details at wally.run/package/1foreverhd/topbarplus.

wally install 1foreverhd/topbarplus