> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infilsense.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install InfilSense UI Library v2 and build a floating Roblox UI in a few minutes.

InfilSense UI Library v2 is a floating Roblox UI library built around draggable, collapsible tabs. Components automatically integrate with Quick Commands, optional keybinds, tooltips, grid snapping, and persistent configuration.

## 1. Install

Load the bundled release directly:

```lua theme={null}
local Library = loadstring(game:HttpGet("https://github.com/bkkpro1980/InfilSense-Lib-v2/releases/latest/download/build.lua"))()
```

The loader expects an environment that provides `loadstring` and `game:HttpGet`. Persistence additionally uses the common file APIs `readfile`, `writefile`, `isfile`, `isfolder`, and `makefolder` when available.

> [!WARNING]
>
> When those file APIs are unavailable, the UI can still be created, but configuration, tab positions, keybinds, and saved slider values cannot be persisted to disk.

## 2. Create the application

`Library.new()` creates the root UI, initializes Quick Commands, loads configuration, and creates the built-in `Settings` tab.

```lua theme={null}
local app = Library.new({
	Name = "My Script",
	SaveFolder = "MyConfigs",
	SaveId = "default",
})
```

Common options are:

| Option | Default | Purpose |
| :- | :- | :- |
| `Name` | `"Unnamed"` | Library name used in state and console output. |
| `SaveFolder` | `""` | Optional folder for the JSON config. |
| `SaveId` | `"config"` | Config file name without `.json`. |
| `Theme` | built-in InfilSense theme | Initial theme table. Pass `Library.Themes.<name>` or a custom table. |
| `AccentColor` | InfilSense accent | Backward-compatible top-level accent override. |
| `TextColor` | InfilSense text | Backward-compatible top-level text override. |

The current default theme is `Library.Themes.InfilSense`. The top-level color settings remain supported for compatibility; the `Theme` table is the preferred API for new code.

## 3. Create a tab

```lua theme={null}
local mainTab = app:CreateTab("Main")
```

New tabs start minimized. Without a saved position or explicit position, they are stacked vertically from the top-left area.

```lua theme={null}
local settingsTab = app:CreateTab(
	"Settings Copy",
	UDim2.new(0, 260, 0, 80)
)
```

> [!NOTE]
>
> Saved tab positions take precedence over `defaultPosition`. Positions are clamped to the available viewport and can use the library's grid snapping settings.

## 4. Add a component

A simple action button:

```lua theme={null}
mainTab:AddButton({
	Info = {
		Title = "Print Hello",
		Description = "Print a test message.",
	},
	Callback = function()
		print("Hello, world!")
	end,
})
```

A stateful toggle:

```lua theme={null}
mainTab:AddButton({
	Info = {
		Title = "Speed Boost",
		Description = "Switch between WalkSpeed 16 and 50.",
	},
	InternalInfo = {
		Toggle = true,
		UniqueCommandId = "speed_boost",
		Aliases = { "speed", "boost" },
	},
	Callback = function(enabled)
		local player = game.Players.LocalPlayer
		local character = player.Character
		local humanoid = character and character:FindFirstChildOfClass("Humanoid")

		if humanoid then
			humanoid.WalkSpeed = enabled and 50 or 16
		end
	end,
})
```

> [!TIP]
>
> Use a stable `UniqueCommandId` for controls that you want to address consistently from Quick Commands, keybinds, or saved configuration.

## 5. Build a small real-world example

This example combines a slider, input, selection, and a toggle:

```lua theme={null}
local ui = Library.new({
	Name = "Demo",
	SaveFolder = "DemoConfig",
	SaveId = "main",
	Theme = Library.Themes.Midnight,
})

local tab = ui:CreateTab("Demo")

tab:AddLabel({
	Text = "Character Controls",
	TextSize = 15,
})

tab:AddSlider({
	Info = { Title = "WalkSpeed" },
	InternalInfo = {
		UniqueCommandId = "walkspeed",
		Aliases = { "ws", "speed" },
	},
	Min = 16,
	Max = 100,
	Default = 16,
	Step = 1,
	Save = true,
	Callback = function(value)
		local character = game.Players.LocalPlayer.Character
		local humanoid = character and character:FindFirstChildOfClass("Humanoid")
		if humanoid then
			humanoid.WalkSpeed = value
		end
	end,
})

tab:AddInput({
	Info = { Title = "Message" },
	DefaultText = "Hello",
	InternalInfo = {
		UniqueCommandId = "message",
		Aliases = { "msg" },
	},
	Callback = function(text)
		print("Message:", text)
	end,
})

local target = tab:AddSelection({
	Info = { Title = "Target" },
	SingleSelect = true,
	DefaultValue = "Nearest",
	InternalInfo = {
		UniqueCommandId = "target",
		Aliases = { "dest" },
	},
	Callback = function(value)
		print("Selected:", value)
	end,
})

target:AddOption({ Info = { Title = "Nearest" }, Value = "Nearest" })
target:AddOption({ Info = { Title = "Self" }, Value = "Self" })
```

## 6. Customize the theme

The library exposes built-in presets through `Library.Themes`. Apply one when creating the application:

```lua theme={null}
local app = Library.new({
	Name = "My Script",
	Theme = Library.Themes.Midnight,
})
```

You can also provide a partial custom theme. Only the channels you include are changed:

```lua theme={null}
local app = Library.new({
	Name = "My Script",
	Theme = {
		accent = Color3.fromRGB(170, 0, 255),
		tabHeading = Color3.fromRGB(255, 255, 255),
		background = Color3.fromRGB(16, 16, 22),
		text = Color3.fromRGB(240, 240, 240),
		inputBackground = Color3.fromRGB(8, 8, 12),
		muted = Color3.fromRGB(120, 120, 130),
		placeholder = Color3.fromRGB(160, 160, 170),
	},
})
```

Themes can be changed after initialization with `app:SetTheme(...)` or one of the individual color setters. See [Theming](https://docs.infilsense.com/features/theming.md) for the complete channel reference, presets, aliases, and runtime behavior.

## 7. Use Quick Commands

Quick Commands opens with **F2** by default.

```text theme={null}
ws 90
speed on
message hello from the command palette
```

Press **Tab** to complete the top matching command and **Enter** to execute it.

> [card] [Application API](https://docs.infilsense.com/api-reference/app.md)
>
> Configure the library, global visibility, themes, tabs, and command export.

> [card] [Component API](https://docs.infilsense.com/api-reference/tab.md)
>
> See every tab builder and the returned component handles.

> [card] [Quick Commands](https://docs.infilsense.com/features/quick-commands.md)
>
> Learn matching rules, aliases, autocomplete, and component-specific arguments.

> [card] [Persistence](https://docs.infilsense.com/features/configuration.md)
>
> Understand saved config files, keybinds, tab state, and slider persistence.

> [card] [Theming](https://docs.infilsense.com/features/theming.md)
>
> Use built-in palettes or customize the library's eight theme channels.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.