1. apireference
2. guiobject

NextSelectionLeft

Property of: GuiObject

Value Type: GuiObject

Code Samples

Creating a Gamepad Selection Grid

This example demonstrates how to enable Gamepad navigation through a grid of GuiObject|GUI elements without manually having to connect the GuiObject/NextSelectionUp, GuiObject/NextSelectionDown, and GuiObject|NextSelectionRight, and GuiObject/NextSelectionLeft properties for every element in the grid.

Note that this code sample assumes your UIGridLayout is sorted by UIGridLayout/SortOrder|name, where elements are named in successive numerical order (see image below).

The code relies on this to set the NextSelection properties for all GuiObjects in the same level as the UIGridLayout. In our example, the UIGridLayoutObject and GUI elements within the grid are all children of a Frame named “Container”. The code Instance/GetChildren|gets the children of “Container” and loops through each child. Children that are not GuiObjects are ignored. For each GUI element, the code attempts to assigned the NextSelection properties using the following logic:

1. Starting with 1, the name of all GUI elements match their position in the grid
2. Left: The item to the left will always be numbered 1 less than the current element
3. Right: The item to the left will always be numbered 1 more than the current element
4. Up: The item above (up) will always be number of GUIs in a row 1 less than the current element
5. Down: The item below (down) will always be the number of GUIs in a row more than the current element
   This logic also allows for the GUI elements at the begging and end of rows (excluding the first and last element) to wrap around to the next and previous rows. If an element doesn’t exist to the left, right, up, or down, the NextSelection will remain nil and moving the Gamepad selector in the direction will not change the selected GUI.

This example also contains code to test the grid using the arrow keys (Up, Down, Left, Right) of your keyboard instead of a gamepad, just in case you don’t have a gamepad to test with. This portion of code initially selects the element named “1” by assigning it to the GuiService/SelectedObject property.

-- ========================================
-- Setup the Gamepad selection grid using the code below
local container = script.Parent:FindFirstChild("Container")
local grid = container:GetChildren()
local rowSize = container:FindFirstChild("UIGridLayout").FillDirectionMaxCells

for i, gui in pairs (grid) do
	if gui:IsA("GuiObject") then
		local pos = gui.Name
		
		-- Left edge
		gui.NextSelectionLeft = container:FindFirstChild(pos-1)		
		-- Right edge
		gui.NextSelectionRight = container:FindFirstChild(pos+1)		
		-- Above
		gui.NextSelectionUp = container:FindFirstChild(pos-rowSize)		
		-- Below
		gui.NextSelectionDown = container:FindFirstChild(pos+rowSize)
	end
end
-- ========================================

-- ========================================
-- Test the Gamepad selection grid using the code below
local GuiService = game:GetService("GuiService")
local UserInputService = game:GetService("UserInputService")

GuiService.SelectedObject = container:FindFirstChild("1")

function updateSelection(input)
	if input.UserInputType == Enum.UserInputType.Keyboard then
		local key = input.KeyCode

		local selectedObject = GuiService.SelectedObject
		if not selectedObject then return end
		
		if key == Enum.KeyCode.Up then
			if not selectedObject.NextSelectionUp then
				GuiService.SelectedObject = selectedObject
			end
		elseif key == Enum.KeyCode.Down then
			if not selectedObject.NextSelectionDown then
				GuiService.SelectedObject = selectedObject
			end
		elseif key == Enum.KeyCode.Left then
			if not selectedObject.NextSelectionLeft then
				GuiService.SelectedObject = selectedObject
			end
		elseif key == Enum.KeyCode.Right then
			if not selectedObject.NextSelectionRight then
				GuiService.SelectedObject = selectedObject
			end
		end
	end
end

UserInputService.InputBegan:Connect(updateSelection)
-- ========================================