The information on this page may no longer be accurate. To see the latest, go to our new and improved documentation. You can also learn more about the future of documentation.

10 min

A table is a Lua data type that can store multiple values including /articles/Numbers|numbers, /articles/Boolean|booleans, /articles/String|strings, /articles/Function|functions, and more. Tables are constructed with curly braces ({}) as shown here:

Once constructed, a table can behave as either an array or a dictionary as illustrated in the following sections.


An array is a simple list of ordered values, useful for storing collections of data such as a group of players with special permissions.

Creating Arrays

To create an array using a Lua table, simply store the values sequentially, separated by commas. An array value can be any non-nil type (boolean, number, string, function, userdata, or even another table).

Reading From Arrays

To read from an array, add a pair of brackets after its reference and specify the index number of the element inside ([pos]):

Writing Into Arrays

The value of an array index can be defined or rewritten by indicating the index number in brackets ([pos]) followed by = and then the value:

Iterating Over Arrays

Arrays can be iterated over (looped through) in two ways:

  • Use the built-in ipairs() function in a for loop.
  • Get the array’s length using the # operator and loop from 1 to that length value.

Inserting Items

An item can be inserted at the end of an array through either of these methods:

  • Pass the array reference and the item value to Lua’s table.insert() function.
  • Add the new item to the array using the t[#t+1] syntax.

An item can also be inserted between the start and end by including a position value as the second argument of table.insert(). This will insert the new item and push the following items up one index position.

Removing Items

An item can be removed from an array with Lua’s table.remove() function. This will remove the item at the specified position and move any following items down one index position.


Dictionaries are an extension of arrays. While an array stores an ordered list of items, a dictionary stores a set of key-value pairs.

Key Value
FruitName Lemon
FruitColor Yellow
Sour true

Creating Dictionaries

To create a dictionary table, define each key followed by = and then the value. Remember to separate each key-value pair with a comma:

When creating dictionaries, keys are not limited to just string names like FruitColor; for example, a key may also be an Instance. In this case, the key must be declared with surrounding brackets ([key]):

Reading From Dictionaries

To read from a dictionary, add a pair of brackets after its reference and specify the key name:

Writing Into Dictionaries

The value of a new or existing dictionary key can be defined by indicating the key name in brackets ([key]) followed by = and then the value:

Iterating Over Dictionaries

Dictionaries can be iterated over with the built-in pairs() function in a for loop:

Removing Key-Value Pairs

To remove a key-value pair from a dictionary, simply set its value to nil. As demonstrated below in the pairs() loop output, this completely erases the key-value pair from the dictionary:

Tables as References

If you store a table in a new variable, a copy of that table is not created. Instead, the variable becomes a reference (pointer) to the original table. This means that any changes to the original table will be reflected in any references:

  • lua
  • coding
  • table
  • array
  • dictionary